Startup failures
These are the most common blockers when launchingollim-bot.
Missing environment variables
config.py validates required variables on import. If any are missing, the
bot prints a message to stderr and exits immediately.
DISCORD_TOKEN is checked separately in main.py:
.env file (at the
project root) and restart.
| Variable | Required | Where checked |
|---|---|---|
DISCORD_TOKEN | Yes | main.py |
OLLIM_USER_NAME | Yes | config.py |
OLLIM_BOT_NAME | Yes | config.py |
Bot already running
The bot writes its PID to~/.ollim-bot/state/bot.pid on startup and checks
/proc/<pid>/cmdline for the string ollim-bot. If a match is found:
atexit.
No owner found
Ifbot.application_info() returns no owner, the bot prints:
Session issues
Session not resuming after restart
Session not resuming after restart
The bot reads If the file contains a JSON object (starts with
~/.ollim-bot/state/sessions.json on startup. If the file is
missing or empty, it starts a fresh session. Check that the file exists
and contains a session ID string:{), load_session_id()
returns None and the bot starts fresh. This can happen if another tool
writes JSON to the file. Replace it with just the session ID string.Frequent compaction events
Frequent compaction events
The Agent SDK auto-compacts conversations when they grow too long. Each
compaction produces a new session ID and a
compacted event in
session_history.jsonl. This is normal behavior — the bot detects the
ID change in save_session_id() and logs it automatically.If compaction happens too frequently, the conversation is growing fast.
Use /clear to start fresh, or use /compact to trigger a manual
compaction at a natural breakpoint.Recovering session history
Recovering session history
The append-only log at Each line is a JSON object with
~/.ollim-bot/state/session_history.jsonl records every
lifecycle event. To inspect it:session_id, event, timestamp, and
parent_session_id. Use this to trace session transitions, find the last
known good session ID, or understand what happened before a crash.To manually resume a specific session, write its ID to sessions.json:Data directory issues
All persistent state lives in~/.ollim-bot/. See the
data directory reference for the full layout.
Corrupt markdown files (routines, reminders, webhooks)
Corrupt markdown files (routines, reminders, webhooks)
read_md_dir() catches ValueError, yaml.YAMLError, TypeError, and
KeyError when parsing .md files. Corrupt files are logged as warnings
and skipped — they do not crash the bot.To find corrupt files, check the bot’s log output for warnings, then
inspect or delete the offending file from ~/.ollim-bot/routines/,
reminders/, or webhooks/.Corrupt JSONL files
Corrupt JSONL files
read_jsonl() skips blank lines and lines that do not start with {.
Lines that start with { but contain invalid JSON raise json.JSONDecodeError
and are not silently dropped — they crash the read. It also filters fields
to only those known to the target dataclass, providing forward compatibility.If a JSONL file is entirely corrupted, delete it. The bot recreates these
files on the next write:Do not edit files while the bot is running
Do not edit files while the bot is running
All writes use atomic temp-file-then-rename (
tempfile.mkstemp +
os.replace). Manual edits to files in ~/.ollim-bot/ while the bot is
running risk being overwritten or causing inconsistent state. Stop the bot
first, make edits, then restart.Google OAuth issues
Missing credentials.json
Missing credentials.json
The Google integration requires
~/.ollim-bot/state/credentials.json from the
Google Cloud Console. Without it, all Google-related commands (tasks,
cal, gmail) and agent tools fail. Follow the
Google OAuth setup guide to create
and place this file.Expired or invalid token
Expired or invalid token
~/.ollim-bot/state/token.json is auto-generated on first authentication and
refreshed automatically. If the token becomes invalid (revoked scopes,
credential rotation), delete it and re-authenticate:Scheduling issues
Routines or reminders not firing
Routines or reminders not firing
The scheduler polls the
routines/ and reminders/ directories every
10 seconds and registers APScheduler jobs. Check:- The bot printed
scheduler started: N jobson startup (visible in the console). - The
.mdfile has valid YAML frontmatter with acron(routines) orrun_at(reminders) field. - The
idfield in the YAML is unique — duplicate IDs cause one to overwrite the other. - The owner was found on startup (no
"warning: no owner found"message). The scheduler does not start without an owner.
Ping budget exhausted
Ping budget exhausted
Background forks that exceed the ping budget get tool errors from
The
ping_user and discord_embed. The user is not notified — the tool
returns an error to the agent, which decides how to proceed.Check the budget state:available field shows remaining pings. The bucket refills 1 ping
per 90 minutes, capped at a capacity of 5. Use /ping-budget in Discord
to view a formatted status. See
ping budget for details.Fork issues
Reply-to-fork not working
Reply-to-fork not working
Fork appears stuck
Fork appears stuck
Interactive forks have an idle timeout. The scheduler checks every 60
seconds — after
idle_timeout minutes of inactivity, it prompts the
agent to exit. After another timeout period, it escalates with a
stronger prompt. The agent always decides the exit strategy
(save_context, report_updates, or exit_fork).If the fork is truly stuck, use the exit buttons on the fork embed, or
run /clear to reset the entire session.Permission issues
Tools being silently denied
Tools being silently denied
The default permission mode is
The
dontAsk. In this mode, non-whitelisted
tools are silently denied without prompting the user in Discord.Switch to a more permissive mode with the /permissions command:| Mode | Behavior |
|---|---|
dontAsk | Non-whitelisted tools silently denied (default) |
default | Non-whitelisted tools trigger Discord approval prompt |
acceptEdits | File edits auto-approved, others prompt |
bypassPermissions | All tools approved |
_session_allowed set persists across interactive forks but resets
on /clear.Approval prompt not appearing
Approval prompt not appearing
In
default or acceptEdits mode, the bot sends a Discord message with
reaction-based approval. The prompt has a 60-second timeout — if you
miss it, the tool is auto-denied. Check that you are in a mode that
sends prompts (default or acceptEdits, not dontAsk).Diagnostic files
Quick reference for where to look when debugging.| File | What it tells you |
|---|---|
~/.ollim-bot/state/sessions.json | Current session ID (or missing = no active session) |
~/.ollim-bot/state/session_history.jsonl | Timeline of session lifecycle events |
~/.ollim-bot/state/bot.pid | PID of running bot instance |
~/.ollim-bot/state/ping_budget.json | Current ping budget state and counters |
~/.ollim-bot/state/pending_updates.json | Queued background fork summaries |
~/.ollim-bot/state/fork_messages.json | Discord message to fork session mappings |
~/.ollim-bot/state/inquiries.json | Active button inquiry prompts |