Troubleshooting — intake docs

Guide to diagnose and resolve common problems with intake.

intake doctor

The first step when facing any problem 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
mcp package	`mcp` package installed (if mcp configured)	Yes
watchfiles	`watchfiles` package installed (if watch configured)	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
GitLab token	`GITLAB_TOKEN` (if gitlab 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 needed 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 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: timeout or network error

Error:

Connector error: Could not write temp file for ...: Connection timed out

or:

Connector error: Could not access repository org/repo: ...

Solution:

Network timeout: verify internet connection and that the service API is available:

# GitHub
curl -s https://api.github.com/rate_limit

# Jira
curl -s https://company.atlassian.net/rest/api/2/serverInfo

# Confluence
curl -s https://company.atlassian.net/wiki/rest/api/space

Expired or invalid token: regenerate the access token and update the environment variable.
Repository or project not found: verify that the repo/project name is correct and that the token has read permissions.
Disk full: if the error mentions “Could not write temp file”, check available disk space.

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:

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`
GitLab	python-gitlab	`pip install python-gitlab`

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
GitLab: Use curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/projects/ID/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 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 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:

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

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

Plugin does not load

Visible error with:

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

Solution:

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

Entry point misconfigured: 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 .
```

MCP server does not start

Error:

ImportError: MCP server requires the mcp package. Install with: pip install intake-ai-cli[mcp]

Solution:

pip install "intake-ai-cli[mcp]"

If you use SSE transport and starlette or uvicorn is missing:

pip install starlette uvicorn

SSE port in use:

Error: [Errno 98] Address already in use

Change the port:

intake mcp serve --transport sse --port 9090

Or in .intake.yaml:

mcp:
  sse_port: 9090

Watch mode does not start

Error:

ImportError: Watch mode requires the watchfiles package. Install with: pip install intake-ai-cli[watch]

Solution:

pip install "intake-ai-cli[watch]"

Spec directory not found:

Watch error: Spec directory not found: specs/my-feature
  Hint: Run 'intake init' first to generate a spec.

Verify that the spec directory exists and contains acceptance.yaml.

acceptance.yaml not found:

Watch error: acceptance.yaml not found in specs/my-feature
  Hint: Run 'intake init' to generate acceptance.yaml.

Regenerate the spec with intake init or verify that the spec was generated in standard or enterprise mode (the quick mode does not generate acceptance.yaml).

GitLab: connection or authentication error

Error:

Connector error: Failed to connect to GitLab at https://gitlab.company.com
  Hint: Check connectors.gitlab.url and GITLAB_TOKEN

Solution:

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

connectors:
  gitlab:
    url: "https://gitlab.company.com"

Verify that GITLAB_TOKEN has a value:

echo $GITLAB_TOKEN   # must have a value

The token needs read_api scope at minimum. For private issues, it needs api.
For self-hosted instances with self-signed certificates:
```
connectors:
  gitlab:
    ssl_verify: false
```
Run intake doctor to validate credentials.

validate: validation errors

Error:

Validation failed: 3 issues found (1 error, 2 warnings)

Solution: This is not an intake error — it is intake validate reporting problems in the spec:

# View the details
intake validate specs/my-feature/ --format json

# Strict mode (warnings are also errors)
intake validate specs/my-feature/ --strict

Common problems it detects:

Category	Example
`structure`	Missing `requirements.md` or `acceptance.yaml`
`cross_reference`	A task references a requirement that does not exist
`consistency`	Cycles in task dependencies
`acceptance`	Check without a defined command
`completeness`	Requirement without a task that implements it

estimate: estimation error

Error:

Error: No sources provided for estimation.

Solution: intake estimate needs at least one source:

intake estimate -s requirements.md -s notes.md

If the model is not in the built-in pricing table, the price of claude-sonnet-4 is used as fallback. You can specify the model:

intake estimate -s reqs.md --model gpt-4o

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
intake validate — validates internal spec consistency
intake estimate — estimates cost (uses local pricing table)
intake mcp serve — runs the MCP server locally
intake watch — monitors files and re-verifies locally

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 generating.

Can I edit the generated specs?

Yes. Specs are regular Markdown and YAML files. You can edit them manually after generating. 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.

What is the 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/my-feature/
intake task update specs/my-feature/ 1 done --note "Completed"