Docs

Reference

Release Notes

Chatbot SDK

Errors & Scenarios

Every common error with its exact fix, four complete end-to-end setup scenarios, and a quick reference cheatsheet for minimal .env configurations.

Startup errorsImport errorsAPI errorsConfig file errorsTroubleshooting table4 scenariosQuick reference

1. Startup / Configuration Errors

These errors are raised before the server accepts any requests. They mean a required environment variable or config file is missing. Fix them in .env or config.ini and restart the server.

EnvironmentError: OPENAI_API_KEY is not set

Add OPENAI_API_KEY=sk-your-key to your .env file and restart. Or set it as a shell variable: export OPENAI_API_KEY=sk-...

EnvironmentError: core.storage = s3 but the following are missing: AWS_OUTPUT_BUCKET, AWS_CONFIG_BUCKET

Set AWS_OUTPUT_BUCKET and AWS_CONFIG_BUCKET in .env. Also set AWS credentials (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY), AWS_PROFILE, or use an IAM role.

EnvironmentError: chatbot_PDF_PATH is not set (pdf_filler=mapper requires a PDF path)

Set chatbot_PDF_PATH=./data/input/blank_form.pdf in .env. Drop your blank PDF at that path first.

EnvironmentError: pdf_filler.provider = managed but these .env keys are missing: AUTH0_DOMAIN, AUTH0_CLIENT_ID, ...

Set all 6 managed mode variables: AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, AUTH0_AUDIENCE, FILL_PDF_LAMBDA_URL, PDF_API_KEY.

2. Import / Module Errors

These errors occur when a required Python package is not installed, or when running from a repo clone without setting PYTHONPATH.

ModuleNotFoundError: No module named 'fastapi'

Run: pip install -r requirements-api.txt Or: pip install fastapi uvicorn python-multipart

ModuleNotFoundError: No module named 'chatbot'

If pip-installed: run pdf-autofillr status to check the install. If from repo clone: run export PYTHONPATH=$(pwd)/src from the repo root before starting any command.

ModuleNotFoundError: No module named 'boto3'

Run: pip install boto3 Or: pip install -r requirements-s3.txt

ImportError: pdf-autofiller-sdk is required for mapper mode

Install the mapper SDK: pip install -r requirements-mapper.txt Or: pip install -e ../mapper/sdks/python/

ImportError: chatbot-managed package required for managed PDF mode

The chatbot-managed package is not open source. Contact your Autofiller account team for access. As an alternative, switch to mapper mode (chatbot_PDF_FILLER=mapper) or data-only mode.

3. API / Runtime Errors

These errors are returned as HTTP responses during normal server operation.

HTTP 400: missing user_id or session_id

Both user_id and session_id are required fields in every POST /chatbot/chat request. Both must be non-empty strings.

HTTP 404 on /mapper/fill (mapper returns 404)

MAPPER_URL_PREFIX is wrong. Use /mapper when running mapper's api_server.py (default). Use an empty string when running mapper's bare fastapi_app.py directly.

HTTP 429: rate limit exceeded

The messages_per_session, sessions_per_user_per_day, or llm_calls_per_session limit was hit. Raise the limits using RateLimitConfig in code, or switch to the Redis backend for accurate distributed counting.

HTTP 500: internal server error

Check the server logs for the full traceback. Most common causes: LLM extraction failure (check OPENAI_API_KEY is valid), storage write failure (check disk permissions or S3 credentials), config file missing or malformed JSON.

HTTP 404: session not found (GET /chatbot/session/{uid}/{sid})

The session is not complete yet - filled_data is only available after session_complete = true in the chat response. Only call GET /session after session_complete appears in the POST /chatbot/chat response.

4. Config File Errors

FileNotFoundError: Required config file not found: configs/form_keys.json

Run: pdf-autofillr setup This creates configs/form_keys.json and all required config files. Then restart the server.

Investor type not loading correct mandatory fields

Investor type names in mandatory.json must exactly match: Individual, Partnership, Corporation, LLC, Trust, Non-Profit Organisations, Fund/Fund of Funds, IRA, Government Bodies, Education Institutions. Check for typos, extra spaces, and wrong capitalisation.

JSONDecodeError when loading config files

One of your JSON config files has a syntax error. Run: python -c "import json; json.load(open('configs/form_keys.json'))" for each file to find the error. Common issues: trailing commas, unquoted keys, single quotes instead of double quotes.

5. Server Port Errors

OSError: [Errno 98] Address already in use (port 8001)

Change the port with PORT=8002 in .env - or find and kill the process: lsof -i :8001 then kill -9 <PID>.

PORT env var overrides config.ini

The PORT environment variable always overrides the server.port value in config.ini. If the server starts on the wrong port, check that PORT is not set in your shell or .env.

6. Troubleshooting Quick Reference

A quick-reference table for the most common problems across all four modules. If the error you are seeing is not listed here, run pdf-autofillr status first — it reports which modules are installed and which are missing required configuration.

ProblemFix

pdf-autofillr setup shows no modules

Run pip install "pdf-autofillr[all]" first, then re-run setup.

EnvironmentError: chatbot_PDF_PATH missing

Set chatbot_PDF_PATH=./data/input/blank_form.pdf in .env.

RAG predictions all empty

RAGPDF_EMBEDDING_BACKEND must be openai (matches bundled vectors). Confirm OPENAI_API_KEY is set.

Mapper not filling PDF

Confirm DOC_UPLOAD_PDF_FILLER=mapper and DOC_UPLOAD_PDF_PATH is set in .env.

LiteLLM noise in terminal

Add LITELLM_LOG=ERROR to .env.

Windows encoding errors in PDF extraction

Add PYTHONUTF8=1 to .env.

Mapper takes too long on unchanged PDF

Enable cache: set pdf_cache_enabled=true under [general] in mapper_config.ini.

Want to use a different embedding model for RAG

Run: ragpdf init-vectors --backend sentence_transformer --force (rebuilds the whole vector DB).

setup shows module installed but status=misconfigured

Run pdf-autofillr status for the specific missing variable, then set it in .env.

doc-upload-cli produces empty output_flat.json

Check DOC_UPLOAD_LLM_MODEL is set and your LLM key is valid. Run with --log-level DEBUG.

Complete setup scenarios

End-to-End Setup Guides

Pick the scenario that matches your deployment target and follow the steps in order. Each scenario is self-contained.

Scenario A - Local development, full stack

install → setup → .env → init-vectors → status → run — complete 7-step flow

terminal

# 1. Create virtual environment and install
python -m venv venv && source venv/bin/activate   # macOS/Linux
# python -m venv venv && .\venv\Scripts\Activate.ps1  # Windows PowerShell
pip install "pdf-autofillr[all]"

# 2. Scaffold project (creates configs/, data/, .env.example)
pdf-autofillr setup

# 3. Copy and fill in your secrets
cp .env.example .env
# Edit .env — minimum: set OPENAI_API_KEY=sk-...
# Also set chatbot_PDF_PATH=data/input/blank_form.pdf

# 4. Drop your blank PDF
cp /path/to/blank_form.pdf data/input/blank_form.pdf

# 5. Initialize RAG vectors (if RAG_ENABLED=true in .env)
ragpdf init-vectors

# 6. Verify all modules are configured
pdf-autofillr status
ragpdf system-info

# 7. Run the chatbot
chatbot-cli --pdf-path data/input/blank_form.pdf --report

# Or start as a server
chatbot-server --host 0.0.0.0 --port 8000

Scenario B - Local dev + mapper PDF filling

Two terminal processes - mapper on :8000, chatbot on :8001

.env + terminal

# .env - chatbot + mapper + RAG (full stack)
OPENAI_API_KEY=sk-...
CHATBOT_LLM_MODEL=openai/gpt-4o-mini
chatbot_PDF_FILLER=mapper
chatbot_PDF_PATH=./data/input/blank_form.pdf
RAG_ENABLED=true
RAG_MODE=inprocess
RAGPDF_EMBEDDING_BACKEND=openai
RAGPDF_OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# mapper_config.ini
# [rag]
# enabled = true
# mode = inprocess

# Run chatbot (mapper and RAG run inprocess - no extra terminals needed)
chatbot-server --host 0.0.0.0 --port 8000

Scenario C - AWS production with S3 storage

EC2 / ECS deployment with IAM role credentials and S3 sessions

.env + terminal

# .env - AWS S3 cloud storage
OPENAI_API_KEY=sk-...
chatbot_PDF_FILLER=mapper
chatbot_PDF_PATH=s3://my-pdf-bucket/blank.pdf
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
STORAGE=s3

# mapper_config.ini
# [general]
# source_type = aws

# Verify S3 configuration
pdf-autofillr status

# Start the server
chatbot-server

Scenario D - AWS Lambda + S3

Serverless deployment - all config via Lambda environment variables

lambda env + event

# Lambda environment variables (AWS console or IaC):
OPENAI_API_KEY=sk-...
chatbot_STORAGE=s3
AWS_OUTPUT_BUCKET=my-chatbot-sessions
AWS_CONFIG_BUCKET=my-chatbot-configs
AWS_REGION=us-east-1
# No AWS credentials needed - Lambda execution role provides access

# Lambda handler:
chatbot.entrypoints.aws_lambda.handler

# Lambda event:
{
  "user_id":    "investor_123",
  "session_id": "session_abc",
  "message":    "my name is John Smith",
  "pdf_path":   "s3://bucket/blank.pdf"
}

6. Quick Reference Cheatsheet

Minimum .env for each common mode. Copy the block that matches your deployment and fill in the placeholder values.

.env - minimum per mode

# ── Chatbot only (data, no PDF) ──────────────
OPENAI_API_KEY=sk-...
CHATBOT_LLM_MODEL=openai/gpt-4o-mini

# ── Chatbot + mapper PDF ──────────────────────
OPENAI_API_KEY=sk-...
CHATBOT_LLM_MODEL=openai/gpt-4o-mini
chatbot_PDF_FILLER=mapper
chatbot_PDF_PATH=./data/input/blank_form.pdf

# ── Doc Upload + mapper PDF ───────────────────
OPENAI_API_KEY=sk-...
DOC_UPLOAD_LLM_MODEL=openai/gpt-4.1-mini
DOC_UPLOAD_PDF_FILLER=mapper
DOC_UPLOAD_PDF_PATH=./data/input/blank_form.pdf

# ── Full stack + RAG ──────────────────────────
OPENAI_API_KEY=sk-...
CHATBOT_LLM_MODEL=openai/gpt-4o-mini
chatbot_PDF_FILLER=mapper
chatbot_PDF_PATH=./data/input/blank_form.pdf
DOC_UPLOAD_LLM_MODEL=openai/gpt-4.1-mini
DOC_UPLOAD_PDF_FILLER=mapper
DOC_UPLOAD_PDF_PATH=./data/input/blank_form.pdf
RAG_ENABLED=true
RAG_MODE=inprocess
RAGPDF_EMBEDDING_BACKEND=openai
RAGPDF_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
LITELLM_LOG=ERROR
PYTHONUTF8=1

# ── S3 cloud storage ─────────────────────────
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
STORAGE=s3

Essential commands

CommandDoes

chatbot-serverStart API server on :8001

chatbot-cliInteractive terminal chatbot session

chatbot-setupInteractive setup wizard

curl localhost:8001/healthCheck server is healthy

curl localhost:8001/docsOpen Swagger UI (browser)

pytest tests/unit/ -vRun unit tests (fast, no network)

docker build -t chatbot-module .Build Docker image

docker run -p 8001:8001 --env-file .env …Run Docker container

Never commit these

.envContains OPENAI_API_KEY and all other secrets

chatbot_data/User session data - may contain investor PII

Safe to commit

config.iniBehaviour settings only - no secrets

configs/*.jsonForm field definitions

DockerfileContainer build instructions

Back to the start

AI SDK OverviewRevisit the overview, capability cards, and install path decision table.Read more ConfigurationFull .env and config.ini reference - every option, every variable.Read more

Advanced AI SDK Overview

Was this page helpful?

PDFFILLR.AI

The intelligent layer for modern fund
administration. Automating high-stakes
documentation with precision and speed.

Powered byEngineersMind

Legal & Privacy

Terms & Conditions

User Agreement

Service Level Agreement

Data Processing Addendum

Resources

API Documentation

Security Overview