Troubleshooting

Run scoutica doctor to automatically check that all prerequisites are installed and configured correctly. It verifies the CLI executable, template directories, schema directories, Python 3, Git, and available AI providers.

scoutica doctor

Installation and shell issues

"scoutica: command not found"

The CLI is installed but not on your PATH. Reload your shell configuration:

source ~/.zshrc    # zsh (default on macOS)
source ~/.bashrc   # bash

If you are using a shell other than zsh or bash, add ~/.scoutica/bin to your PATH manually:

export PATH="$HOME/.scoutica/bin:$PATH"

Restart your terminal session if reloading the shell config does not help.

Git not configured for publish

scoutica publish requires Git to be installed and configured with a name and email. If publish fails with a Git error:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Also ensure you have a remote origin set in your card directory:

git remote -v    # should show your GitHub repo URL

If no remote is set, add one:

git remote add origin https://github.com/your-username/your-card-repo.git

Scan and document issues

Scan shows "No readable documents found"

The CLI did not find any supported files in the specified directory.

Supported formats: .md .txt .pdf .docx .json .yaml .csv .html

Check that your document folder contains files with these extensions:

ls ~/my-docs/

If your files have other extensions (e.g., .pages, .odt), export or convert them to a supported format before scanning.

PDF text extraction fails

PDF processing requires pdftotext from the Poppler library.

brew install poppler          # macOS
apt install poppler-utils     # Ubuntu / Debian
dnf install poppler-utils     # Fedora / RHEL

Verify installation:

pdftotext -v

If your PDFs are image-based (scanned documents), pdftotext cannot extract their contents. Convert them using an OCR tool first.

"Empty response from provider"

The CLI found an AI provider binary but received no output. Verify your AI CLI is installed and working:

gemini --version      # Gemini CLI
claude --version      # Claude Code
ollama list           # Ollama

If the command fails, reinstall the provider. If Ollama is running but returns an empty response, ensure a model is pulled:

ollama pull llama3

You can also explicitly specify a working provider:

scoutica scan ~/my-docs/ --with ollama

Schema validation failures

scoutica validate checks your card files against the protocol’s JSON Schemas. Common causes of failure:

Missing required field — the error message names the field and file. Check profile.json for required fields like name, title, and seniority.
Invalid enum value — seniority must be one of: junior, mid, senior, lead, principal, staff.
Malformed JSON or YAML — use a linter to check syntax:

python3 -m json.tool profile.json     # validate JSON
python3 -c "import yaml; yaml.safe_load(open('rules.yaml'))"  # validate YAML

After fixing, re-run validation:

scoutica validate ./my-card/

Network issues

Network or SSRF errors in resolve

scoutica resolve and scoutica jobs share one strict fetch boundary. It accepts only HTTPS public destinations, rejects credentials and mixed/private DNS answers, does not use proxies or follow redirects, and validates response size, media type, UTF-8, and JSON shape.

If you see a URL validation error, check that:

The URL uses https://, not http://
The URL points to a public host and every DNS answer is public
The server returns 200 directly rather than a 3xx redirect
JSON resources use application/json, text/json, or raw-host text/plain and stay within 2 MiB
Supported URL formats:
- https://github.com/user/repo
- https://raw.githubusercontent.com/user/repo/main/
- Any direct HTTPS URL hosting card files

scoutica resolve https://github.com/username/my-card

If the target repo is private, scoutica resolve cannot fetch it. The card repository must be public.

Still stuck?

Run scoutica doctor for a full diagnostic report, then check the GitHub Issues page. Include the output of scoutica doctor and the full error message when reporting a bug.