Troubleshooting¶

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

CLI: owl command not found¶

Symptom:

command not found: owl

Resolution:

• Windows: Close the current PowerShell window, reopen it, and try again
• Linux / macOS: Close the current terminal window, reopen it, and try again
• 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: Failed to upgrade from a legacy testing version¶

If owl --version displays testing-<SHA>, confirm that the current update channel provides a new installation script, and then run owl update. The new script migrates such legacy builds to the official release of the currently configured channel without requiring you to replace the CLI or switch 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 a testing- prefix followed by a 7- to 40-character hexadecimal Git SHA. Unknown, corrupted, or non-executable versions are not forcibly overwritten as legacy versions. After confirming the cause, refer to Manual Installation to reinstall.

Auto Installation: AI Tool Cannot Execute Commands¶

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

Resolution:

• Switch to an AI tool that supports terminal command execution
• Or use Manual Installation instead

Auto Installation: Invalid, Expired, or Unauthorized Temporary Authorization Credential¶

Cause: OWL_TEMP_CODE has expired, has already been used, was copied incorrectly, or the current account does not have permission to generate authorization codes.

Resolution:

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

Auto Installation: Endpoint Mismatch¶

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

Resolution:

• Re-select the OWL CLI Endpoint based on the node where the workspace resides
• Fill in only the Endpoint root address for OWL_REGISTRY_ENDPOINT
• For private deployment environments, use the OWL CLI Endpoint provided by the actual deployment

CLI: Authentication Failure or Endpoint Unreachable¶

Check the following:

• Whether OWL_REGISTRY_ENDPOINT is the OWL CLI Endpoint for the current site
• Whether /api/v1 was incorrectly appended to the Endpoint
• Whether the access token is valid. Both OWL_API_KEY and OWL_TOKEN can be used as access tokens; when both are set, OWL_API_KEY takes precedence
• Whether the API Key has the corresponding Open API permissions
• Whether the current terminal can access the OWL CLI Endpoint

CLI: HTTPS Certificate Verification Failure¶

If local development or private test environments use self-signed certificates, the CLI may return x509: certificate signed by unknown authority. Install a trusted CA in the system first; if installation is truly not possible, you can temporarily run:

owl config set registry.insecure_skip_verify true

This configuration disables Registry identity verification and may be vulnerable to man-in-the-middle attacks. It is intended only for 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 Prematurely¶

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

owl config set registry.request_timeout 180000

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

CLI: tool not found Error¶

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

Resolution:

owl sync
owl list

Confirm the tool name and run the command again.

CLI: category not found Error¶

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

Resolution:

owl sync
owl category list

CLI: missing required parameter Error¶

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 Error¶

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

Resolution:

owl show <tool-name>

Check the parameter name and run the command again.

CLI: owl validate Returns a Validation Failure¶

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

First distinguish between a validation failure result and a validation command failure:

• If 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, validation is incomplete. Do not execute the tool; after troubleshooting sync, authentication, network, or Registry availability, run the validation again.

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

• tool / tool_not_found: Run owl sync first, and then confirm that the tool name exactly matches the output of owl list;
• parameter / invalid_arguments: Fix missing parameters, wrong 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 see a message that there is no validate command, upgrade to version 1.2.0 or later. The preflight check that generates DQL for simple queries requires version 1.2.1 or later.

CLI: Empty or Unexpected Results¶

Check in the following order:

1. Use owl show <tool-name> to check the parameter definitions
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 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 for the current site
• Whether the URL ends with /mcp
• Whether the request header contains 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 that the API Key belongs to is the workspace you want to access

Request header format:

Authorization: Bearer <API Key>

Note: The /mcp endpoint authenticates before establishing the event stream. If the credentials are missing or invalid, it returns HTTP 401 Unauthorized directly (with a WWW-Authenticate: Bearer realm="mcp" response header) instead of opening a text/event-stream. Therefore, if the client reports that it is "connected but the event stream is empty," first confirm whether a 401 was in fact received — 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. Re-test 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 Calls Return 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 permissions for read-only scenarios
• Grant the corresponding write permissions for write scenarios
• It is not recommended to configure overly broad API Key permissions for an Agent

MCP: Tool Calls Return Empty Results¶

Check in the following order:

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

MCP: Write Operations Blocked or Not Taking Effect¶

Possible causes:

• The API Key does not have write permissions
• The client is configured for manual confirmation, but the confirmation was not provided
• The parameter structure does not meet the tool requirements
• Approval or audit restrictions exist 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 approval, audit, or permission configurations on the workspace side