Troubleshooting

Guide for diagnosing and resolving common problems with intake.

intake doctor

The first step for any problem is to run intake doctor:

intake doctor

This verifies:

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
Jira credentials	`JIRA_API_TOKEN` + `JIRA_EMAIL` (if jira configured)	No
Confluence credentials	`CONFLUENCE_API_TOKEN` + `CONFLUENCE_EMAIL` (if confluence configured)	No
GitHub token	`GITHUB_TOKEN` (if github configured)	No

Auto-fix

To automatically fix problems 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 relative paths from 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 necessary pages with another tool

URL not accessible

Error:

Failed to parse 'https://example.com/page': Connection error: ...
  Hint: Check that the URL is correct and accessible.

Solution: intake could not download the page. Verify:

That the URL is correct and accessible from your network
That it does not require authentication (intake does not support URLs with login)
That there is no firewall or proxy blocking the connection

If the page requires authentication, download the content manually and use the local file:

# Instead of
intake init "Feature" -s https://internal-wiki.com/page  # fails if login required

# Download manually and use the file
curl -o page.html https://internal-wiki.com/page
intake init "Feature" -s page.html

Connector cannot connect

Error:

Connector error: Failed to connect to Jira at https://company.atlassian.net
  Hint: Check connectors.jira.url and credentials in .intake.yaml

Solution:

Verify that the base URL is correct in .intake.yaml:

connectors:
  jira:
    url: "https://company.atlassian.net"

Verify that the environment variables are configured:

echo $JIRA_API_TOKEN    # must have a value
echo $JIRA_EMAIL        # must have a value

Run intake doctor to validate connector credentials.
If the API requires VPN or firewall, verify the network connection.

Connector not available (missing dependency)

Error:

Connector 'jira' requires atlassian-python-api.
  Hint: Install with: pip install "intake-ai-cli[connectors]"

Solution:

# Install connector dependencies
pip install "intake-ai-cli[connectors]"

Optional packages for connectors are:

Connector	Package	Installation
Jira	atlassian-python-api	`pip install atlassian-python-api`
Confluence	atlassian-python-api	`pip install atlassian-python-api`
GitHub	PyGithub	`pip install PyGithub`

Alternative without installing connectors: Export the data manually:

Jira: Export issues as JSON from the web interface
Confluence: Export the page as HTML
GitHub: Use gh api repos/org/repo/issues > issues.json

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
```
Lower 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 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 without 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`
URLs	httpx, beautifulsoup4, markdownify	`pip install httpx beautifulsoup4 markdownify`

Plugin does not load

Visible with:

intake plugins list -v   # The "Error" column shows the detail
intake plugins check     # Reports FAIL with details

Solution:

External plugin not installed: verify that the package is installed in the same environment:
```
pip list | grep my-plugin
```

Misconfigured entry point: verify that pyproject.toml has the correct entry_point:

[project.entry-points."intake.parsers"]
my-format = "my_plugin.parser:MyParser"

Import error: the plugin module fails to import. Verify the plugin’s dependencies.
Reinstall: sometimes entry_points are not updated without reinstalling:
```
pip install -e .
```

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 enclosed 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 — verifies 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 configured 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 generation.

Can I edit the generated specs?

Yes. Specs are regular Markdown and YAML files. You can edit them manually after generation. 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/mi-feature/ -s new-reqs.md

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

Can I use intake in CI/CD?

Yes. See the CI/CD Integration section for detailed examples.

Should spec files be committed to git?

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

What is quick / standard / enterprise mode?

intake auto-detects the complexity of your sources and selects a generation mode:

quick (<500 words, 1 simple source): only generates context.md + tasks.md
standard (default): generates all 6 complete spec files
enterprise (4+ sources or >5000 words): all files + detailed risks

You can force a mode with --mode:

intake init "Quick fix" -s bug.txt --mode quick

How do I install external plugins?

Plugins are automatically discovered when installing packages that register entry_points in the intake.parsers, intake.exporters, or intake.connectors groups:

pip install my-intake-plugin
intake plugins list   # the new plugin should appear

See Plugins for more details.

How do I view task progress?

intake task list specs/mi-feature/
intake task update specs/mi-feature/ 1 done --note "Completed"