Troubleshooting¶

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

v1.7.0: Upgrades and Call Results¶

• On DQL failure, inspect query_text, raw_output, and issues[].message for the reason and available line/column details. time.validation_unavailable means the checker is unavailable, not a query syntax error. Review original query text before sharing diagnostics.
• After a document version change, search again and use the new reference. Do not access the Registry filesystem. See document reading.
• If runtime mode rejects Profile/configuration changes, ask the executor to check the three runtime variables together. Do not switch identity to bypass the lock. See runtime Profiles.
• For pending or uncertain catalog writes, follow write confirmation. Do not create a new UUID and repeat the write.

v1.6.0: Time Validation or Sync Failure¶

Use issues[].code to identify time errors. For time.unit, check timestamp units and integer types. For time.pair, supply both values. For time.order, correct their order. For time.span, reduce the window. Remove relative or conflicting DQL windows, or use an absolute window that matches the external range. For time.validation_unavailable, check the Registry's dqlcheck, then run preflight again.

owl sync returns failure if any category download fails. It keeps the failed category's previous cache and local version. An initial automatic sync failure blocks execution. An automatic sync failure after cache expiry continues to warn and use the existing cache.

CLI: owl command not found¶

Symptom:

command not found: owl

Resolution:

• Windows: Close the current PowerShell, reopen it, and run the command again
• Linux / macOS: Close the current terminal window, reopen it, and run the command 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 legacy testing versions¶

If owl --version shows testing-<SHA>, confirm that the current update channel provides the new installation script, then run owl update. The new script supports migrating such legacy builds to the official version of the current configuration 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 executes properly 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 will not be forcibly overwritten as old versions. After confirming the cause, refer to manual installation to reinstall.

Automatic installation: The AI tool cannot execute commands¶

Cause: The current AI tool does not have terminal command execution permission, 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 is invalid, expired, or unauthorized¶

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 the temporary authorization credential in the TrueWatch console
• Re-execute 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 where the Workspace is located, or /api/v1 was incorrectly appended.

Resolution:

• Re-select the OWL CLI Endpoint according to the node where the Workspace is located
• OWL_REGISTRY_ENDPOINT should contain only the Endpoint root address
• For private deployment environments, use the OWL CLI Endpoint provided by the actual deployment

CLI: Authentication failure or Endpoint inaccessible¶

First, check the effective identity and configuration source:

owl profile current -f json
owl config show

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

Check the following:

• Whether the effective Endpoint is the OWL CLI Endpoint of the site to which the Workspace belongs
• Whether /api/v1 was incorrectly appended to the Endpoint
• Whether the access token of the selected Profile is valid; in scenarios where environment variable overrides apply, when both OWL_API_KEY and OWL_TOKEN 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: Wrong Profile selected¶

Use owl profile list and owl profile current -f json to check local aliases, persisted defaults, 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 fails¶

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

CLI: HTTPS certificate verification fails¶

If your local development or private test environment uses self-signed certificates, the CLI may return x509: certificate signed by unknown authority. Prefer installing a trusted CA on the system. 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 expose you to man-in-the-middle attacks. Use it only in controlled development environments; never enable it 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 check registry.request_timeout. This value is in milliseconds and defaults to 150000; the server-side deadline for data query tools 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 does not extend the server-side query deadline. If the query still fails, narrow the time range, reduce the returned volume, 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.

Each Profile has an 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 re-run the command.

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>

Complete the required parameters according to the tool definition and re-run the command.

CLI: unknown parameter error¶

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

Resolution:

owl show <tool name>

Verify the parameter name and re-run the command.

CLI: owl validate returns a 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 an invalid validation result from a failed validation command:

• When the JSON contains valid: false, do not execute the tool; fix the parameters according to the kind and code in issues.
• When the command exits with a non-zero status code or does not output a validation JSON result, the validation was not completed. Do not execute the tool; after troubleshooting sync, authentication, network, or Registry availability, run the 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 the tool name exactly matches the owl list output;
• 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 retry the same parameters directly.

If the validate command is not available, upgrade to version 1.2.0 or later. Preflight checks for DQL generated from simple queries require version 1.2.1 or later.

CLI: Empty results or results not as expected¶

Check in the following order:

1. Use owl show <tool name> to verify the parameter definitions
2. Use owl list -c <category ID> to confirm 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 corresponding Open API permissions for the resource

MCP: Client connection fails¶

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. If credentials are missing or invalid, it returns HTTP 401 Unauthorized directly (with the WWW-Authenticate: Bearer realm="mcp" response header) without opening the text/event-stream 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. Fix the credentials according to the 401 and WWW-Authenticate header, then retry.

MCP: Empty tool list¶

Possible causes:

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

Resolution:

1. Re-test the MCP connection in the client
2. Confirm the Endpoint matches the site of the Workspace
3. Confirm 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 directly for Agents

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 discovery tools such as owl.metric.list or owl.log_index.list need to be called first
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 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 conform to the tool requirements
• There are approval or audit restrictions on the Workspace side

Resolution:

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