/
Troubleshooting center

Troubleshooting center

Introduction

The Troubleshooting Center extend our diagnostic capabilities to provide your teams with direct visibility into system operations. This new feature centralizes technical logs allowing you to identify and resolve blockers without contacting OneStock support.

Thanks to the details provided, you can instantly distinguish between a configuration error, a third-party service outage, or an authentication mismatch.

Access

The troubleshooting center is available directly in the backoffice as the other menus.

This menu is available only to users with the following roles:

  • Client Admin

image-20260325-134622.png

Diagnostic Scope

  • Carrier Integrations: View the exact request and response payloads from shipping partners to debug label generation or tracking failures.

  • API ACL (Access Control): Identify precisely why a request was rejected, whether due to missing permissions, expired tokens, or incorrect scoping.

  • Workflow Operations: Trace the logic of order state transitions to understand why an order might be "stuck" or why a specific automation failed to trigger.

This feature helps teams maintain high operational uptime by turning technical "black boxes" into actionable data.

Troubleshooting logs are available for a period of 14 days

Troubleshooting user guide

How to find specific logs

Logs details

When an issue occurs, the interface creates a new log entry containing:

  • Time of the error

  • Error area

  • Related order, user, and endpoint IDs (if existing)

  • Message giving an initial description of the issue

  • Metadata providing additional information on the API call to help identify the error cause

image-20260325-143633.png
ACL log details

Filters

image-20260325-140756.png

To facilitate log search, multiple filters are available:

  • Order, User, and Stock location filters help find logs linked to a specific ID

  • Area filter limits logs to a particular scope

  • Date range selects a specific timeframe (default: last 14 days)

Filter button must be clicked to apply filters selected

ACL logs

ACL errors occur when accessing unauthorized endpoints with current role permissions. Metadata details provide information to explain this denied access. You can find the following fields:

  • “action” is the method used in the API call (GET, POST, PATCH, DELETE)

  • “policy_id” is the ID of the policy denying access

  • “policy_desc” describes the policy and clarifies the restriction

  • “ressource” is the endpoint route called

For example, if an API call returns an “acl_error” response, the “policy_desc” field explains why the call was blocked.

Carriers logs

Carrier errors can block label generation or pick-up requests. The metadata field shows the request from OneStock and the response from the Carrier service.

In the “request” field:

  • “body” contains the sent request message

  • “headers” contains the request headers

  • “method” is the API call method

  • “sent_at” is the request timestamp

  • “url” is the reached endpoint

In the “response” field from the external carrier:

  • “body” contains the response message

  • “error” describes the error, aiding issue diagnosis

  • “headers” contains the response headers

  • “received_at” is the response timestamp

  • “status_code” is the response status code

For example, if a store has a label generation error, search the log by Stock Location IDs and analyze the “error” in the “response”. A line in the message may contain an invalid character. Find it in the “body” of the “request”, then fix it in the order details page.

Workflow logs

Workflow errors occur when a transition is impossible or blocked by a condition. The Message and Metadata fields provide details to clarify the cause. The Metadata includes:

  • “entity_id” is the OneStock ID of the entity that raised the error

  • “entity_type” is the entity type

  • “from_state” is the original state of the transition

  • “to_state” is the destination state of the transition

  • “workflow_name” is the workflow linked to the entity blocking the transition

For example, if transitioning an item from "out of stock" to "placed" raises an error, the error logs will help identify the cause, which may involve another linked entity such as the order

External integration

Export logs

You can extract the filtered logs as a JSONL document directly from the Troubleshoot interface thanks to the export button. It contains the data available in the interface, such as Metadata, Message, and other fields. This exported file is useful for:

  • Sharing specific error snapshots with third-party technical partners

  • Conducting long-term audits in your internal tools

Real time webhooks

Subscribe to the following topics to receive instant alerts in your own monitoring system:

  • acl_error_occurred alerts for permission denials

  • carrier_error_occurred alerts for shipping or pick-up failures (such as label generation errors or invalid addresses)

  • workflow_error_occurred alerts for transition errors in orchestration

With the information received, you can identify the impacted entities, determine the error cause, and plan the appropriate mitigation.

You can subscribe to these new topics by following the existing process Webhooks and find the details of each topic within the List of standard webhook topics.