Troubleshooting

Guide for diagnosing and resolving common issues with intake.

intake doctor

The first step when facing any issue is to run intake doctor:

intake doctor

This checks:

Check	What it verifies	Auto-fixable
Python version	Python >= 3.12	No
LLM API key	Environment variable configured	No
pdfplumber	Package installed	Yes
python-docx	Package installed	Yes
beautifulsoup4	Package installed	Yes
markdownify	Package installed	Yes
litellm	Package installed	Yes
jinja2	Package installed	Yes
Config file	Valid `.intake.yaml`	Yes

Auto-fix

To automatically fix issues that can be resolved:

intake doctor --fix

This:

Installs missing packages using pip3.12, pip3 or pip (in that order of preference)
Creates .intake.yaml if it does not exist, with basic configuration

Common Errors

API Key Not Configured

Error:

LLM error: Environment variable ANTHROPIC_API_KEY is not set.
  Hint: Set it with: export ANTHROPIC_API_KEY=your-api-key

Solution:

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# OpenAI
export OPENAI_API_KEY=sk-your-key-here

If you use another provider, configure llm.api_key_env in .intake.yaml:

llm:
  model: gemini/gemini-pro
  api_key_env: GEMINI_API_KEY

Verify with:

intake doctor

File Not Found

Error:

Failed to parse 'reqs.md': File not found: reqs.md
  Hint: Check that the file exists and the path is correct.

Solution: Verify that the file path is correct. Use paths relative to the current directory or absolute paths:

# Relative
intake init "Feature" -s ./docs/reqs.md

# Absolute
intake init "Feature" -s /home/user/project/docs/reqs.md

Empty File

Error:

Failed to parse 'empty.md': File is empty or contains only whitespace
  Hint: Provide a file with actual content.

Solution: The file exists but has no useful content. Add content to the file before using it as a source.

File Too Large

Error:

Failed to parse 'huge.pdf': File size 52428800 bytes exceeds limit of 50 MB
  Hint: Split the file into smaller parts or extract the relevant sections.

Solution: The limit is 50 MB. Options:

Split the file into smaller parts
Extract only the relevant sections
If it is a PDF, extract the needed pages with another tool

Unsupported Format

Error:

Unsupported format: 'xlsx' for source 'data.xlsx'

Solution: intake does not support Excel files directly. Options:

Export to CSV or JSON from Excel
Copy the content to a text or Markdown file
Convert to another supported format (see Input Formats)

Budget Exceeded

Error:

LLM error: Accumulated cost $0.5123 exceeds limit of $0.50
  Hint: Increase llm.max_cost_per_spec in your config, or use a cheaper model.

Solution: The analysis exceeded the configured budget. Options:

Increase the limit:
```
llm:
  max_cost_per_spec: 1.00
```

Use a cheaper model:

intake init "Feature" -s reqs.md -m gpt-3.5-turbo

Disable risk assessment (saves ~30%):
```
spec:
  risk_assessment: false
```

Use the minimal preset:

intake init "Feature" -s reqs.md --preset minimal

LLM Does Not Return Valid JSON

Error:

LLM error: LLM did not return valid JSON after 3 attempts
  Hint: Try a different model or simplify the prompt.

Solution: The model could not generate valid JSON after the configured retries. Options:

Try a different model — some models are better at generating structured JSON:
```
intake init "Feature" -s reqs.md -m claude-sonnet-4
```
Increase retries:
```
llm:
  max_retries: 5
```
Reduce the temperature for more deterministic output:
```
llm:
  temperature: 0.1
```
Simplify the sources — very long or complex texts can confuse the model.

LLM Timeout

Error:

LLM failed after 3 attempts: Request timed out
  Hint: Check your API key, network connection, and model name.

Solution:

Check your internet connection
Increase the timeout:
```
llm:
  timeout: 300  # 5 minutes
```

Verify that the model exists — incorrect names cause timeouts:

# Correct
llm:
  model: claude-sonnet-4

# Incorrect -- will cause timeout or error
llm:
  model: claude-sonet-4  # typo

Encoding Error

If a file has non-UTF-8 encoding, intake tries to read it with a fallback to latin-1. If it still fails:

Solution:

Convert the file to UTF-8:

iconv -f ISO-8859-1 -t UTF-8 file.txt > file_utf8.txt

Or open it in an editor and save as UTF-8.

PDF With No Extractable Text

Error:

Failed to parse 'scanned.pdf': PDF contains only scanned images, no extractable text
  Hint: Use an image source instead.

Solution: The PDF contains scanned images, not digital text. Options:

Use external OCR to extract the text first

Export the pages as images and use the image parser:

intake init "Feature" -s page1.png -s page2.png

Missing Package for Parser

Error:

PDF parsing requires pdfplumber.
  Hint: Install it with: pip install pdfplumber

Solution:

# Install manually
pip install pdfplumber

# Or use doctor --fix to install everything missing
intake doctor --fix

Optional packages per parser:

Parser	Package	Installation
PDF	pdfplumber	`pip install pdfplumber`
DOCX	python-docx	`pip install python-docx`
Confluence	beautifulsoup4, markdownify	`pip install beautifulsoup4 markdownify`

Invalid acceptance.yaml

Error:

Verification failed: Invalid YAML in acceptance.yaml: ...
  Hint: Check acceptance.yaml syntax.

Solution: The acceptance.yaml file has YAML syntax errors. Check:

Correct indentation (use spaces, not tabs)
Strings with special characters in quotes
Lists with - followed by a space

# Correct
checks:
  - id: check-01
    name: "Tests pass"
    type: command
    command: "python -m pytest tests/ -q"

# Incorrect -- missing space after -
checks:
  -id: check-01

FAQ

Do I need internet to use intake?

Only for intake init and intake add (which require LLM calls). Everything else works offline:

intake verify — runs checks locally
intake export — generates files locally
intake show / intake list — reads local files
intake diff — compares local files
intake doctor — checks the local environment

Can I use local models?

Yes. intake uses LiteLLM, which supports local models via Ollama, vLLM, and others:

llm:
  model: ollama/llama3
  api_key_env: DUMMY_KEY  # Ollama does not need a key

export DUMMY_KEY=not-needed
intake init "Feature" -s reqs.md

What language is the spec generated in?

English by default (en). It is configurable with --lang or project.language:

intake init "Feature" -s reqs.md --lang es

project:
  language: es

The language affects the content generated by the LLM, not the file structure.

How much does it cost to generate a spec?

It depends on the model, the amount of text, and the enabled options:

Scenario	Approximate cost
Small source, minimal preset, Claude Sonnet	~$0.02-0.05
Medium source, standard preset, Claude Sonnet	~$0.05-0.15
Multiple sources, enterprise preset, Claude Sonnet	~$0.15-0.50
GPT-3.5 instead of Claude	~50-70% less

Use intake show to see the actual cost after generating.

Can I edit the generated specs?

Yes. Specs are normal Markdown and YAML files. You can edit them manually after generating them. However, if you use intake add --regenerate, your manual edits will be overwritten.

How do I update a spec with new requirements?

# Add a new source
intake add specs/my-feature/ -s new-reqs.md

# Or regenerate everything with the new source
intake add specs/my-feature/ -s new-reqs.md --regenerate

Can I use intake in CI/CD?

Yes. See the CI/CD integration section in the verification guide.

Should spec files be committed to git?

Yes, it is recommended. Specs are text files that benefit from versioning. See Spec Versioning.