Skip to content
Marmot Development Kit

Troubleshooting

Authentication and credentials

Section titled “Authentication and credentials”

”Not authenticated” / login loops

Section titled “”Not authenticated” / login loops”

Run:

Terminal window
uv run komodo login

Complete the browser OAuth flow. Make sure the CLI and SDK use the same account (see Authentication).

Wrong or missing account (UnsetAccountError)

Section titled “Wrong or missing account (UnsetAccountError)”

You may see: An account_id was not passed and could not be read from the SDK client session.

  1. Run
    Terminal window
    uv run komodo account set
    and pick an account.
  2. Or pass account_id= into get_snowflake_connection(...) (and JWT or M2M credentials as needed).

See Accounts.

Custom credentials file path

Section titled “Custom credentials file path”

If you use KOMODO_CREDENTIALS_PATH, the CLI and SDK must agree on the same path. See Credentials file configuration.

M2M: ValueError about JWT vs client secret

Section titled “M2M: ValueError about JWT vs client secret”

You cannot pass both jwt and client_id/client_secret. Use one auth mode only. See Authentication types.

Snowflake and queries

Section titled “Snowflake and queries”

Connection works but queries fail (database / role / syntax)

Section titled “Connection works but queries fail (database / role / syntax)”
  • Run USE DATABASE, USE SCHEMA, and USE ROLE as required for your account. Examples use DATA and roles your admin assigned.
  • Prefer starting with INFORMATION_SCHEMA queries from the Quickstart and Executing Queries guides.

Diagnosing a failed query

Section titled “Diagnosing a failed query”

When a query fails, the SDK surfaces the full Snowflake error — message, error code, SQL state, and query ID — rather than a generic message. For example:

Komodo Error: Failure during expansion of view 'MEDICAL_SERVICE_LINES_LATEST': Error in secure object. | Error code: 002003 | SQL state: 02000 | Query ID: 01b... (Trace ID: ...)

To dig deeper into a specific query without contacting Komodo support:

  1. Capture the query ID from the error (Query ID: ...) or from cursor.sfqid.

  2. Fetch recorded diagnostics — error code/message, execution status, warehouse, and timing:

    from komodo import get_query_diagnostics
    print(get_query_diagnostics(conn, query_id))

    or from the CLI:

    Terminal window
    uv run komodo sql-diagnostics <query-id>

Diagnostics are read from Snowflake’s INFORMATION_SCHEMA.QUERY_HISTORY for your role/account, so a database must be set on the connection (e.g. USE DATABASE DATA) and the query must be within the history retention window. If you still cannot determine the cause (for example a Error in secure object from a view you do not own), include the query ID and trace ID when reporting the issue. See get_query_diagnostics.

Long-running or blocked queries

Section titled “Long-running or blocked queries”

Use Async Queries with execute_query_async for submit-and-poll flows. Remember blocking I/O behavior described there.

Pandas warnings

Section titled “Pandas warnings”

If pandas warns about non-SQLAlchemy connectables, the connection is still valid. See Pandas Integration.

MCP server

Section titled “MCP server”

MCP cannot find komodo or fails to start

Section titled “MCP cannot find komodo or fails to start”
  • cwd in MCP config must be the project directory where uv can run komodo (directory with pyproject.toml that depends on komodo).
  • Use the same command / args as in MCP Server (uv run komodo mcp run).

Schema exploration fails but CLI works

Section titled “Schema exploration fails but CLI works”

Re-run

Terminal window
uv run komodo account set
and confirm the account matches what you expect. In Komodo internal environments, extra MCP tools may be available when internal extensions are installed.

App Builder builds (internal)

Section titled “App Builder builds (internal)”

These apply when komodo-internal-tools is installed (build_app MCP tool or komodo build).

komodo build --local / build_mode: local — BuildKit errors

Section titled “komodo build --local / build_mode: local — BuildKit errors”
  • Install buildctl and ensure it is on PATH (brew install buildkit on macOS).
  • Default BUILDKIT_HOST: docker-container://buildkitd (container must be named buildkitd). If that fails, use TCP:
    Terminal window
    docker run -d --name buildkitd --privileged -p 1234:1234 moby/buildkit:latest --addr tcp://0.0.0.0:1234
    export BUILDKIT_HOST="tcp://127.0.0.1:1234"
    komodo build check
  • build_app (MCP) vs CLI: export BUILDKIT_HOST in a terminal fixes komodo build --local only. For build_app in Cursor, set BUILDKIT_HOST on the Komodo MCP server (Settings → MCP → komodo → Environment), or ensure the default docker-container://buildkitd works from the MCP process.
  • You do not need AWS_ROLE_ARN or AWS CLI for ECR; local mode uploads an image tar through the Build API (OAuth only).

Details: App Builder — BUILDKIT_HOST.

Upload or prebuilt failures

Section titled “Upload or prebuilt failures”

Large image tars need a stable network; retry once. If the Build API returns an error after upload, use build_id with komodo build status or get_build_scan_report (MCP) for details.

Installation

Section titled “Installation”

Python version errors

Section titled “Python version errors”

The SDK requires Python 3.10+. See Installation.

Still stuck?

Section titled “Still stuck?”