Troubleshooting¶

This document addresses common issues encountered when connecting OWL CLI and OWL MCP Server.

CLI: Prompt owl not found¶

Symptom:

command not found: owl

Resolution:

• Windows: Close the current PowerShell window and reopen it before executing the command again.
• Linux / macOS: Close the current terminal window and reopen it before executing the command again.
• Verify that the executable file exists in the default installation directory.

Default executable paths:

• Windows: %LOCALAPPDATA%\Programs\owl\owl.exe
• Linux / macOS: $HOME/.local/bin/owl; falls back to /usr/local/bin/owl if the default path is not writable.

Automatic Installation: 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 configurations.

Resolution:

• Switch to an AI tool that supports terminal command execution.
• Or use manual installation instead.

Automatic Installation: Temporary authorization code is invalid, expired, or not authorized¶

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

Resolution:

• Regenerate a temporary authorization code in the TrueWatch console.
• Re-execute the installation command from the automatic installation guide.
• Do not reuse an OWL_TEMP_CODE that has already been used.

Automatic Installation: Endpoint mismatch¶

Cause: OWL_REGISTRY_ENDPOINT is inconsistent with the site of the workspace, or /api/v1 was incorrectly appended to the endpoint.

Resolution:

• Select the OWL CLI Endpoint for the node where the workspace is located.
• Set OWL_REGISTRY_ENDPOINT to only the root address of the endpoint.
• For private deployment environments, use the OWL CLI Endpoint provided by the actual deployment.

CLI: Authentication failed or unable to reach the endpoint¶

Check the following:

• Is OWL_REGISTRY_ENDPOINT set to the OWL CLI Endpoint of the current site?
• Was /api/v1 incorrectly appended to the endpoint?
• Is the access token valid? Both OWL_API_KEY and OWL_TOKEN can be used as access tokens. When both are set, OWL_API_KEY takes precedence.
• Does the API Key have the corresponding Open API permissions?
• Can the current terminal reach the OWL CLI Endpoint?

CLI: HTTPS certificate verification failed¶

If a self-signed certificate is used in a local development or private test environment, the CLI may return x509: certificate signed by unknown authority. First, try to install a trusted CA for the system. If this is not possible, you can temporarily disable certificate verification:

owl config set registry.insecure_skip_verify true

This configuration turns off registry identity verification, which may expose the system to man-in-the-middle attacks. It should only be used in controlled development environments and must not be enabled in production. To re-enable verification, run owl config set registry.insecure_skip_verify false.

CLI: Long-running query times out prematurely¶

If a data query returns context deadline exceeded, first check the network and registry status, then inspect registry.request_timeout. This value is in milliseconds and defaults to 150000. The server-side limit for data query tools is 130 seconds, so it is not recommended to set the client-side total 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 data returned, or simplify the query conditions.

CLI: Prompt tool not found¶

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 re-execute.

CLI: Prompt category not found¶

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

Resolution:

owl sync
owl category list

CLI: Prompt 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 re-execute.

CLI: Prompt unknown parameter¶

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

Resolution:

owl show <tool_name>

Verify the parameter names and re-execute.

CLI: owl validate returns validation failure¶

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

First, distinguish between a failed validation result and a failed validation command:

• If the JSON contains valid: false, do not execute the tool. Correct the parameters based on the kind and code in the issues array.
• 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. After troubleshooting synchronization, authentication, network, or registry availability, run the validation again.

For valid: false results, handle based on the kind and code in issues:

• tool / tool_not_found: First run owl sync, then ensure the tool name exactly matches the output of owl list.
• parameter / invalid_arguments: Correct missing parameters, incorrect types, or unknown parameters all at once based on the list of issues.
• dql_syntax / dql.parseError: Correct the query_text of owl.data.query.
• generated_dql / dql.builderError: Correct the select_clause, where_clause, or group_by_clause of the simple query. Do not retry with the same parameters.

If the validate command is not available, upgrade to version 1.2.0 or later. Pre-check for DQL generation from simple queries requires version 1.2.1 or later.

CLI: Results are empty or 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 that the correct tool is being executed.
3. Run 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 fails¶

Check the following:

• Is the MCP type configured as streamableHttp?
• Is the URL the OWL MCP Endpoint for the current site?
• Does the URL end with /mcp?
• Does the request header include Authorization: Bearer <API Key>?
• Can the client's network reach the OWL MCP Endpoint?

MCP: Authentication failure¶

Check the following:

• Is the API Key copied correctly?
• Is the Authorization Header format correct?
• Has the API Key been disabled, deleted, or rotated?
• Does the workspace associated with the API Key match the workspace you are trying 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 directly returns an HTTP 401 Unauthorized (with a 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, not 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 successfully connect to the service.
• The API Key is invalid or has insufficient permissions.
• The client did not refresh the MCP tool list.
• The endpoint was selected incorrectly.

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 call returns a permission error¶

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

Resolution:

• Check the API Key's permission scope.
• For read-only scenarios, grant the corresponding query permissions.
• For write scenarios, grant the corresponding write permissions.
• It is not recommended to configure overly broad API Key permissions for an agent.

MCP: Tool call returns an empty result¶

Check in the following order:

1. Is the query time range correct?
2. Do the selected data domain, source, field, and index exist?
3. Is it necessary to first call discovery tools, such as owl.metric.list or owl.log_index.list?
4. Does the API Key have read permissions for that data scope?
5. Does the corresponding data actually exist in the current workspace?

MCP: Write operation is blocked or not effective¶

Possible causes:

• The API Key does not have write permissions.
• The client is configured with 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 the workspace-side approval, audit, or permission configurations.