Troubleshooting

quadkit Command Not Found

Cause: The package is not installed or the virtual environment is not activated.

Solution:

uv add quadkit-cli
# or run via uv without installing:
uv run quadkit --help

ConfigNotFoundError — Configuration File Not Found

Exception: quadkit.cli.ConfigNotFoundError

Cause: A CLI command that needs project context (run, dev, db, inspect, gen) was run outside a project directory.

Solution:

# Create an application.yaml in the current directory
quadkit init

# Or run from the project root
cd my-project

ProviderNotInstalledError — Provider Not Installed

Exception: quadkit.cli.ProviderNotInstalledError

Cause: A command requires a package that is not installed — for example, the provider behind db.

Solution:

uv add quadkit-web    # for web-related generators
# install the extension that provides the missing provider

Generator Not Found

Cause: The generator’s contributing package is not installed.

Solution:

uv add quadkit-web    # or the relevant package
quadkit gen list      # verify it appears

Entry Point Not Detected

Cause: quadkit run or quadkit dev could not find create_app() in the project.

Solution:

# Specify the entry point explicitly
quadkit run my_app.app:create_app

# Or ensure your app module defines create_app() or 'app' at module level

Server Backend Not Available

Cause: The preferred server backend (Granian, Uvicorn) is not installed.

Solution:

uv add uvicorn
# or
uv add granian

The CLI auto-detects available backends and falls back gracefully.

CLI config TOML parse error

Error: Failed to parse config file at ~/.config/quadkit/config.toml

Cause: The TOML config file contains syntax errors — missing quotes, invalid tables, or trailing commas.

Fix: Validate the TOML file:

uv run python -c "import tomllib; tomllib.load(open('~/.config/quadkit/config.toml', 'rb'))"

The default config is created by ConfigManager.save() and should be valid. If the file is corrupted, delete it and let the CLI recreate it:

rm ~/.config/quadkit/config.toml

Generator fails with package import error

Error: Generator 'web-api' failed: No module named 'quadkit-web'

Cause: The generator’s contributing package (quadkit-web, etc.) is not installed. Generators are discovered via entry points and may declare optional dependencies.

Fix: Install the required package:

uv add quadkit-web
quadkit gen list  # verify it appears

Server backend detection fails

Warning: No ASGI server backend found. Install uvicorn or granian.

Cause: Neither uvicorn nor granian is installed in the current environment. quadkit run and quadkit dev require an ASGI server to serve the application.

Fix: Install a server backend:

uv add uvicorn
# or for better performance:
uv add granian

The CLI prefers Granian when available and falls back to Uvicorn.

Output shows raw ANSI color codes

Symptom: Terminal output contains literal escape sequences like [32m instead of colored text.

Cause: The terminal does not support ANSI color codes (pipe/redirect, CI output, or NO_COLOR environment). The CLI detects terminal capabilities but may not disable color when output is piped.

Fix: Disable colors explicitly:

quadkit --no-color <command>
# or
QK_CLI__COLOR=false quadkit <command>

For scripted output, use --json for machine-readable results:

quadkit system info --json