Troubleshooting¶

This document is used to handle 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 and reopen it, then execute again.
• Linux / macOS: Close the current terminal window and reopen it, then execute again.
• Confirm if 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, falling back to /usr/local/bin/owl if not writable.

Auto-installation: AI tool cannot execute commands¶

Reason: The current AI tool does not have terminal command execution permissions, 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-installation: Temporary authorization credential invalid, expired, or unauthorized¶

Reason: OWL_TEMP_CODE has expired, been used, 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 command from Auto-installation.
• Do not reuse an OWL_TEMP_CODE that has already been used.

Auto-installation: Endpoint mismatch¶

Reason: OWL_REGISTRY_ENDPOINT does not match the site where the workspace is located, or /api/v1 is incorrectly appended.

Resolution:

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

CLI: Authentication failed or cannot access Endpoint¶

Check the following:

• Is OWL_REGISTRY_ENDPOINT the Owl CLI Endpoint for the current site?
• Is the Endpoint incorrectly appended with /api/v1?
• Is OWL_TOKEN valid?
• Does the API Key have the corresponding Open API permissions?
• Can the current terminal access the Owl CLI Endpoint?

CLI: Prompt tool not found¶

Reason: 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 execute again.

CLI: Prompt category not found¶

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

Resolution:

owl sync
owl category list

CLI: Prompt missing required parameter¶

Reason: Required parameters are missing.

Resolution:

owl show <tool_name>

Fill in the required parameters according to the tool definition and execute again.

CLI: Prompt unknown parameter¶

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

Resolution:

owl show <tool_name>

Check the parameter name and execute again.

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

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 contain Authorization: Bearer <API Key>?
• Can the client's network access the Owl MCP Endpoint?

MCP: Authentication failed¶

Check the following:

• Was the API Key copied correctly?
• Is the Authorization Header format correct?
• Has the API Key been disabled, deleted, or rotated?
• Is the workspace to which the API Key belongs the current workspace to be accessed?

Request header format:

Authorization: Bearer <API Key>

MCP: Tool list is empty¶

Possible reasons:

• 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.
• Endpoint selection is incorrect.

Resolution:

1. Re-test 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¶

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

Resolution:

• Check the API Key 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. Is the query time range correct?
2. Do the selected data domain, source, field, index exist?
3. Is it necessary to call discovery tools first, e.g., owl.metric.list, 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 blocked or not taking effect¶

Possible reasons:

• API Key does not have write permissions.
• Client is configured for manual confirmation but confirmation was not given.
• Parameter structure does not meet tool requirements.
• There are approval or audit restrictions on the workspace side.

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.