Troubleshooting¶

This document addresses common access issues for 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, then retry.
• Linux / macOS: Close the current terminal window and reopen it, then retry.
• Confirm 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, falling back to /usr/local/bin/owl if not writable.

Auto-install: AI tool cannot execute commands¶

Cause: The current AI tool lacks permission to execute terminal commands, or the current environment prohibits writing to local configuration.

Resolution:

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

Auto-install: Temporary authorization credential invalid, expired, or unauthorized¶

Cause: The OWL_TEMP_CODE has expired, been used, was copied incorrectly, or the current account lacks permission to generate authorization codes.

Resolution:

• Regenerate the temporary authorization credential in the Guance console.
• Re-execute the installation command from the Auto-install guide.
• Do not reuse an OWL_TEMP_CODE that has already been used.

Auto-install: Endpoint mismatch¶

Cause: The 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 based on the node where the workspace is located.
• For OWL_REGISTRY_ENDPOINT, 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 failure or unable to access Endpoint¶

Check the following:

• Whether OWL_REGISTRY_ENDPOINT is the Owl CLI Endpoint for the current site.
• Whether the Endpoint incorrectly appends /api/v1.
• Whether the access token is valid. Both OWL_API_KEY and OWL_TOKEN can be used as access tokens. If 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 cached locally, 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.

Resolution:

owl sync
owl category list

CLI: Prompt missing required parameter¶

Cause: Required parameters are 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 name and re-execute.

CLI: Empty result or result does not match expectations¶

Check in the following order:

1. Use owl show <tool name> to verify 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 if the query time range is correct. Time parameters should be 13-digit millisecond timestamps.
5. Check if the API Key has Open API permissions for the corresponding resources.

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 client's network 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 current workspace to be accessed.

Request header format:

Authorization: Bearer <API Key>

Note: The /mcp endpoint performs authentication before establishing the event stream. If credentials are missing or invalid, it directly returns HTTP 401 Unauthorized (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 if it actually received a 401—this is usually an authentication issue rather than an empty stream. Please correct the credentials based on the 401 and the WWW-Authenticate header and retry.

MCP: Tool list is empty¶

Possible causes:

• MCP client failed to connect to the service successfully.
• API Key is invalid or has insufficient permissions.
• Client did not refresh the MCP tool list.
• Incorrect Endpoint selected.

Resolution:

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

MCP: Tool call returns permission error¶

Cause: The API Key lacks the corresponding Open API permissions.

Resolution:

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

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, index exists.
3. Whether discovery tools need to be called first, e.g., owl.metric.list, 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 operation blocked or not taking effect¶

Possible causes:

• API Key lacks write permissions.
• Client configured for manual confirmation but confirmation was not given.
• Parameter structure does not meet tool requirements.
• Workspace side has approval or audit restrictions.

Resolution:

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