Troubleshooting¶

This document is used to address common access issues with OWL CLI and OWL MCP Server.

CLI: Prompt owl not found¶

Phenomenon:

command not found: owl

Solution:

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

Default executable file paths:

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

Auto Installation: AI tool cannot execute the command¶

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

Solution:

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

Auto Installation: Temporary authorization credential is invalid, expired, or not authorized¶

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

Solution:

• Regenerate a temporary authorization credential in the TrueWatch console
• Re-execute the installation command from Auto Installation
• Do not reuse an already used OWL_TEMP_CODE

Auto Installation: Endpoint mismatch¶

Cause: OWL_REGISTRY_ENDPOINT is inconsistent with the site where the workspace is located, or /api/v1 was incorrectly appended.

Solution:

• Re-select the OWL CLI Endpoint according to the node where the workspace is located
• OWL_REGISTRY_ENDPOINT should only fill in 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 access Endpoint¶

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: Prompt tool not found¶

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

Solution:

owl sync
owl list

After confirming the tool name, re-execute.

CLI: Prompt category not found¶

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

Solution:

owl sync
owl category list

CLI: Prompt missing required parameter¶

Cause: A required parameter is missing.

Solution:

owl show <tool_name>

After completing the required parameters according to the tool definition, re-execute.

CLI: Prompt unknown parameter¶

Cause: The parameter name is inconsistent with the tool definition.

Solution:

owl show <tool_name>

After verifying the parameter name, re-execute.

CLI: Result is 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. Use owl sync to refresh the local cache
4. Check whether the query time range is correct. The time parameter should be a 13-digit millisecond timestamp
5. Check whether the API Key has the corresponding resource's Open API permissions

MCP: Client connection failed¶

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 client's network can access the OWL MCP Endpoint

MCP: Authentication failed¶

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 currently being accessed

Request header format:

Authorization: Bearer <API Key>

Note: The /mcp endpoint authenticates before establishing an event stream. When credentials are missing or invalid, it directly returns HTTP 401 Unauthorized (with a WWW-Authenticate: Bearer realm="mcp" response header) without opening a text/event-stream event stream. Therefore, if the client reports "connected but event stream is empty", you should first confirm whether a 401 was actually received -- this is usually an authentication issue rather than an empty stream. Please correct the credentials based on the 401 and WWW-Authenticate header and 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

Solution:

1. Re-test the MCP connection in the client
2. Confirm that the Endpoint is consistent with the workspace site
3. Confirm that the Authorization Header is correct
4. Reload or restart the MCP client

MCP: Tool call returns permission error¶

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

Solution:

• Check the scope of the API Key's permissions
• 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 call returns empty result¶

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, e.g., owl.metric.list, 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 operation is blocked or not effective¶

Possible causes:

• The API Key does not have write permissions
• The client is configured with manual confirmation but it was not confirmed
• The parameter structure does not meet the tool's requirements
• There are approval or audit restrictions on the workspace side

Solution:

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