Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tldrwtf/pokedo/llms.txt

Use this file to discover all available pages before exploring further.

If something isn’t working as expected, this page covers the most common issues and how to resolve them. Check the relevant accordion below for your error message or symptom.
The pokedo command is not on your PATH. This usually means the virtual environment is not active or the package was not installed correctly.
  1. Activate your virtual environment: 
    source venv/bin/activate  # On Windows: venv\Scripts\activate
  2. Try running PokeDo directly through Python: 
    python -m pokedo
  3. If the command is still missing, reinstall the package: 
    pip install -e .
PokeDo requires an initialized database before any commands will work. If you see a database error on first run, the ~/.pokedo/pokedo.db file either does not exist or could not be created.
  1. Run the initialization command: 
    pokedo init --name "YourName"
  2. If the error persists, check that you have write permissions in your home directory: 
    ls -la ~ | grep .pokedo
    If the .pokedo directory exists but is not writable, update its permissions or delete it and re-run init.
Full initialization fetches data for all 1025 Pokemon from the PokeAPI, which can take several minutes on slower connections.Use one of these flags to speed things up:
  • Gen 1 only — downloads 151 Pokemon instead of 1025: 
    pokedo init --name "YourName" --quick
  • Specific generation — replace N with the generation number (1–9): 
    pokedo init --name "YourName" --gen N
  • Parallel requests — increase concurrency to fetch data faster: 
    pokedo init --name "YourName" --concurrency 20
Terminal sprite rendering requires a terminal emulator that supports inline images. Supported terminals include iTerm2, Kitty, and WezTerm. In any other terminal, PokeDo falls back to a text representation automatically — this is expected behavior and not a bug.If sprites are not loading at all, check whether the sprite cache exists:
ls ~/.pokedo/cache/sprites/
An empty directory means the sprites have not been downloaded yet. Complete a task or run pokedo sprite <name> to trigger a download.
The PokeAPI is free and has generous rate limits. If you see rate-limiting errors during initialization, the most likely cause is running many parallel requests at very high concurrency.Keep in mind:
  • All Pokemon data is cached locally after the first successful fetch. Subsequent runs do not make API requests.
  • If you suspect a stale or corrupted cache, clear it by deleting the cache directory: 
    rm -rf ~/.pokedo/cache/
    The next init or command that needs Pokemon data will re-fetch and re-cache everything.
Symptom: Exiting the task screen in the TUI raises:
TypeError: cannot use 'pokedo.core.task.Task' as a dict key (unhashable type: 'Task')
Cause: This was a naming conflict between PokeDo’s domain Task model and Textual’s internal Widget._task asyncio lifecycle field. If a screen or widget stored a domain Task in self._task, Textual would treat it as an asyncio task, causing a crash when it tried to use it as a dictionary key.Status: Fixed in current code. State fields have been renamed to _detail_task, _editing_task, and _completed_task to avoid the collision. If you are working on a fork or customizing TUI components, do not store domain objects in self._task.If you are still seeing this error, ensure you are on the latest version:
git pull origin main
pip install -e .
Battle commands require a running PokeDo server. If you see ConnectionRefusedError or similar errors:
  1. Confirm the server is running: 
    # Using Docker Compose (recommended)
docker-compose up -d

# Or manually
uvicorn pokedo.server:app --port 8000
  2. Check the POKEDO_SERVER_URL environment variable. The default is http://localhost:8000. If your server is on a different host or port, set it explicitly: 
    export POKEDO_SERVER_URL=http://your-server:8000
  3. If a battle is stuck in pending state, the opponent must accept the challenge and both players must submit their teams before the battle becomes active.

​
Reset and start fresh

If your data is corrupted or you want a clean slate, you can remove all PokeDo data and reinitialize.
This permanently deletes your trainer profile, caught Pokemon, task history, and all cached data. This action cannot be undone.
rm -rf ~/.pokedo
pokedo init --name "YourName"

Build docs developers (and LLMs) love

Get started for freeTalk to us