Troubleshooting¶

This document helps you resolve common integration issues with the OWL CLI and OWL MCP Server.

v1.7.0: Upgrade and Call Results¶

• When a DQL fails, check query_text, raw_output, and issues[].message for the specific cause and available row/column information; time.validation_unavailable means the validator is unavailable and should not be treated as a query syntax error. Before sharing diagnostics, inspect the raw query content in them.
• After a documentation version change, search again and use the new read_reference; do not access the Registry filesystem. See DQL Document Reading.
• When configuration or Profile operations are rejected in runtime mode, have the executor check whether the three runtime variables are injected as a group; do not switch identity to bypass the restriction. See Runtime Profiles.
• If a catalog write is pending or the audit is indeterminate, follow the Write Result and Confirmation Process; do not generate a new UUID and write again.

v1.6.0: Time Validation or Sync Failures¶

Time errors can be distinguished by issues[].code: time.unit checks the timestamp unit and integer type, time.pair completes paired parameters, time.order corrects the ordering, and time.span narrows an out-of-range window. DQL relative windows or conflicting windows should be removed or changed to absolute windows consistent with the external range; for time.validation_unavailable, check the Registry's dqlcheck, then retry the preflight.

owl sync returns failure when any category download fails, preserving the existing cache and local version of the failed category. A failed first auto-sync blocks subsequent execution; a failed auto-sync after cache expiration still warns and uses the existing cache, as before.

CLI: owl Command Not Found¶

Symptom:

command not found: owl

Resolution:

• Windows: Close the current PowerShell, reopen it, and then run the command
• Linux / macOS: Close the current terminal window, reopen it, and then run the command
• Confirm whether the executable exists in the default installation directory

Default executable paths:

• Windows: %LOCALAPPDATA%\Programs\owl\owl.exe
• Linux / macOS: $HOME/.local/bin/owl, falling back to /usr/local/bin/owl if not writable

CLI: Legacy Testing Version Upgrade Failure¶

If owl --version shows testing-<SHA>, confirm that the current update channel provides a new installation script, then run owl update. The new script can migrate such historical builds to the official version of the currently configured channel, without replacing the CLI or switching channels first.

If you still see failed to parse local owl version or failed to read local owl version, check whether owl --version runs successfully and whether the version is a supported official release or testing- followed by a 7- to 40-character hexadecimal Git SHA. An unknown, corrupted, or failing version will not be forcibly overwritten as an older version. After confirming the cause, you can reinstall by referring to Manual Installation.

CLI and Skill Issues in Agents¶

Whether the CLI executes, whether the Skill is recognized, and whether the business call succeeds are three separate checks. Finally, confirm the actual returned result according to First-Call Verification.

Automatic Installation: The AI Tool Cannot Execute Commands¶

Cause: The current AI tool does not have terminal command execution permissions, or the current environment prohibits writing to local configuration.

Resolution:

• Use an AI tool that supports terminal command execution
• Or switch to Manual Installation

Automatic Installation: Temporary Authorization Credential Invalid, Expired, or Not Authorized¶

Cause: OWL_TEMP_CODE is expired, already used, incorrectly copied, or the current account lacks permission to generate an authorization code.

Resolution:

• Regenerate the temporary authorization credential in the Guance console
• Re-run the installation instructions in Automatic Installation
• Do not reuse an OWL_TEMP_CODE that has already been used

Automatic Installation: Endpoint Mismatch¶

Cause: OWL_REGISTRY_ENDPOINT does not match the site of the workspace, or /api/v1 was incorrectly appended.

Resolution:

• Choose the OWL CLI Endpoint again based on the node where the workspace resides
• Fill in only the Endpoint root address for OWL_REGISTRY_ENDPOINT
• For private deployments, use the OWL CLI Endpoint provided by the actual deployment

CLI: Authentication Failure or Unable to Access Endpoint¶

First, check the identity and configuration source currently in effect:

owl profile current -f json
owl config show

After a Profile is selected (including default), the entire Endpoint/Key set comes from that Profile; modifying OWL_REGISTRY_ENDPOINT, OWL_API_KEY, or OWL_TOKEN will not override it. These environment variables override the configuration file only in legacy configuration mode or when --conf is used alone.

Check the following:

• Whether the Endpoint currently in effect is the OWL CLI Endpoint of the site to which the workspace belongs
• Whether /api/v1 was incorrectly appended to the Endpoint
• Whether the selected Profile's access token is valid; in scenarios where environment variable overrides apply, OWL_API_KEY takes precedence when both OWL_API_KEY and OWL_TOKEN are set
• Whether the API Key has the corresponding Open API permissions
• Whether the current terminal can access the OWL CLI Endpoint

CLI: The Wrong Profile Was Selected¶

Use owl profile list and owl profile current -f json to check local aliases, the persisted default, and the actual selection. The selection priority is --profile > OWL_PROFILE > the default saved by owl switch. Adding a new Profile does not switch to it; --profile affects only the current command.

owl --profile customer-a config show
owl --profile customer-a sync
owl --profile customer-a exec owl.data.show_dql_namespace

switch does not accept --profile, --conf, or OWL_PROFILE. See Using Multiple Profiles.

CLI: profile remove --purge Cleanup Failure¶

Check the permissions of the managed directory indicated in the error, fix the permissions, and retry the removal. If artifact cleanup fails, the configuration and credentials are retained, the alias is restored, and some cache or query files may have been deleted. To keep artifacts, use owl profile remove <alias> without --purge.

CLI: HTTPS Certificate Verification Failure¶

If a local development or private test environment uses a self-signed certificate, the CLI may return x509: certificate signed by unknown authority. Prefer installing a trusted CA for the system; if installation is genuinely not possible, you can temporarily run:

owl config set registry.insecure_skip_verify true

This setting disables Registry identity verification and may expose you to man-in-the-middle attacks. It may be used only in controlled development environments and must not be enabled in production. To restore verification, run owl config set registry.insecure_skip_verify false.

CLI: Long-Running Queries Time Out Early¶

If a data query returns context deadline exceeded, first check the network and Registry status, then review registry.request_timeout. This value is in milliseconds and defaults to 150000; the server-side deadline for the data query tool is 130 seconds, so it is not recommended to set the client total timeout shorter than that.

owl config set registry.request_timeout 180000

Increasing the client timeout will not extend the server-side query deadline. If the query still fails, narrow the time range, reduce the returned data volume, or simplify the query conditions.

CLI: tool not found¶

Cause: The tool is not in the local cache, or the tool name is entered incorrectly.

Each Profile has its own independent tool cache. After switching Profile, Endpoint, or Key, run owl sync under the same Profile.

Resolution:

owl sync
owl list

Confirm the tool name and run the command again.

CLI: category not found¶

Cause: The category name does not exist or has not been synced yet.

Resolution:

owl sync
owl category list

CLI: missing required parameter¶

Cause: A required parameter is missing.

Resolution:

owl show <tool_name>

Fill in the required parameters according to the tool definition and run the command again.

CLI: unknown parameter¶

Cause: The parameter name does not match the tool definition.

Resolution:

owl show <tool_name>

Verify the parameter name and run the command again.

CLI: owl validate Returns Validation Failure¶

owl validate only performs a preflight check and does not invoke the target tool. request_executed in the JSON result should always be false.

First distinguish between a result that fails validation and a failure of the validation command:

• When the JSON contains valid: false, do not execute the tool; fix the parameters according to the kind and code in issues.
• If the command exits with a non-zero status code, or does not output a validation JSON result, the validation is incomplete. Do not execute the tool; troubleshoot sync, authentication, network, or Registry availability, then run validation again.

For valid: false results, handle them according to the kind and code in issues:

• tool / tool_not_found: Run owl sync first, then confirm that the tool name exactly matches the output of owl list;
• parameter / invalid_arguments: Fix missing parameters, incorrect types, or unknown parameters all at once according to the issue list;
• dql_syntax / dql.parseError: Fix the query_text of owl.data.query;
• generated_dql / dql.builderError: Fix the select_clause, where_clause, or group_by_clause of the simple query; do not simply retry with the same parameters.

If you are told that there is no validate command, upgrade to 1.2.0 or later. Preflight validation of DQL generation for simple queries requires 1.2.1 or later.

CLI: Results Are Empty or Not as Expected¶

Check the following items in order:

1. Use owl show <tool_name> to check the parameter definition
2. Use owl list -c <category_id> to confirm that the correct tool is being executed
3. Use owl sync to refresh the local cache
4. Check whether the query time range is correct; time parameters should be 13-digit millisecond timestamps
5. Check whether the API Key has the Open API permissions for the corresponding resource

MCP: Client Connection Failure¶

Check the following:

• Whether the MCP type is configured as streamableHttp
• Whether the URL is the OWL MCP Endpoint of the current site
• Whether the URL ends with /mcp
• Whether the request header includes Authorization: Bearer <API Key>
• Whether the network where the client resides can access the OWL MCP Endpoint

MCP: Authentication Failure¶

Check the following:

• Whether the API Key was copied correctly
• Whether the Authorization header format is correct
• Whether the API Key has been disabled, deleted, or rotated
• Whether the workspace to which the API Key belongs is the workspace you intend to access

Request header format:

Authorization: Bearer <API Key>

Note: The /mcp endpoint authenticates before establishing the event stream. When credentials are missing or invalid, it returns HTTP 401 Unauthorized directly (with the WWW-Authenticate: Bearer realm="mcp" response header) and does not open a text/event-stream. Therefore, if the client reports "connected but the event stream is empty", first confirm whether it actually received a 401—this is usually an authentication issue rather than an empty stream. Correct the credentials based on the 401 and the WWW-Authenticate header, then retry.

MCP: Tool List Is Empty¶

Possible causes:

• The MCP client did not connect to the service successfully
• The API Key is invalid or has insufficient permissions
• The client has not refreshed the MCP tool list
• The wrong Endpoint was selected

Resolution:

1. Retest the MCP connection in the client
2. Confirm that the Endpoint matches the workspace site
3. Confirm that the Authorization header is correct
4. Reload or restart the MCP client

MCP: Tool Call Returns a Permission Error¶

Cause: The API Key does not have the corresponding Open API permissions.

Resolution:

• Check the API Key permission scope
• Grant the corresponding query permission for read-only scenarios
• Grant the corresponding write permission for write scenarios
• It is not recommended to configure overly broad API Key permissions directly for the Agent

MCP: Tool Call Returns an Empty Result¶

Check the following items in order:

1. Whether the query time range is correct
2. Whether the selected data domain, source, field, and index exist
3. Whether discovery tools need to be called first, such as owl.metric.list and owl.log_index.list
4. Whether the API Key has read permission for that data scope
5. Whether the corresponding data actually exists in the current workspace

MCP: Write Operations Blocked or Not Applied¶

Possible causes:

• The API Key does not have write permission
• The client is configured for manual confirmation, but no confirmation was provided
• The parameter structure does not meet the tool requirements
• There are approval or audit restrictions on the workspace side

Resolution:

1. Check the tool parameters
2. Check the API Key permissions
3. Check whether the client is waiting for manual confirmation
4. Check the workspace-side approval, audit, or permission configuration