Codex Desktop / log health check / Mika tutorial

Codex Crashed? Check logs_2.sqlite First After Reinstalling

A student recently found their Codex Desktop completely unresponsive. Updating to the latest version didn't fix it. A full reinstall was the only way back. Reinstalling can restore the app, but local tasks and work context may disappear along the way. This article walks through why logs_2.sqlite should be your first stop after a reinstall, and how to set up a regular log health check going forward.

Mika the detective holding a magnifying glass, inspecting a Codex crash and the logs_2.sqlite database
Cover illustration in Mika tutorial style. The focus of this article is a safe health-check and backup workflow, not deleting logs arbitrarily.

What This Article Covers

Using a real crash case from a student as the starting point, this article addresses four things: what the local log database logs_2.sqlite actually is, how to handle it safely when Codex won't open, how to set up an automated health check that runs every three to five days, and how to make sure your work survives even when the tool breaks down. The technical references are drawn from related issues and source code in the OpenAI Codex GitHub repo, not from any official announcement.

Who This Is For
  • You rely on Codex Desktop every day, and one day it simply refuses to open no matter how many times you try.
  • You've updated to the latest version or even reinstalled, and you're still worried the same thing could happen again.
  • You've heard of logs_2.sqlite, WAL, and VACUUM but aren't sure whether to touch them or whether doing so could make things worse.
  • Your biggest fear is that a broken tool takes your recent tasks and work context down with it.
What You'll Take Away
  • A clear understanding of what logs_2.sqlite is and what it isn't, and why it can drag down Codex's startup.
  • A conservative handling sequence for crashes: back up first, inspect first, avoid deleting unless necessary.
  • A health-check automation prompt you can paste directly into Codex, with inspection-only mode as the default.
  • A work habit that keeps your knowledge assets safe even when tools fail.

What Actually Happened

The student's Codex Desktop kept refusing to open. The screen displayed an error with signal=SIGKILL, config.toml, and suggestions to update Codex or reload. Updating to the latest version still didn't resolve it. A full reinstall was what finally brought it back.

Codex error screen showing SIGKILL and config warnings
Crash screenshot one: the error message includes SIGKILL and a config warning. When you see this kind of screen, checking the local log database is worth doing alongside hitting the update button.
Codex showing an error even after updating to the latest version
Crash screenshot two: even after updating to the latest version, existing local state issues don't necessarily go away.
Enlarged view of the Codex crash screen with SIGKILL error and a breakdown of the recommended handling steps
An annotated view of the same case: the top half shows the actual crash screen, the bottom half outlines the handling steps covered in this article, ending with the key takeaway: logs can be cleared, but your tasks and work belong in your own files.
Reinstalling Is a Starting Point, Not an Ending One A reinstall can bring the app back online, but it may also wipe local tasks, conversation state, and your current work context. The actual impact depends on the version, installation method, and whether your local data folder was cleared. The better sequence is to back up first, inspect first, and move only the log database if that's enough. If you've already reinstalled, the first thing to do is set up a health check so the problem doesn't quietly grow back.

Getting the Framing Right

It's easy to describe this situation as "OpenAI officially says Codex has this bug." The accurate framing requires more caution.

Where the Evidence Comes From

Multiple related issues in the OpenAI Codex GitHub repo point to risks such as an oversized logs_2.sqlite, a corrupt log database, a WAL file that keeps growing, or high-volume TRACE log writes. These are community reports and maintainer discussions, not official announcements.

How to Interpret It

logs_2.sqlite is one plausible cause worth checking first. It is not the single definitive answer for every Codex crash. There may be other causes at play. This article focuses on the part that leaves a traceable trail and can be safely inspected on your own.

Getting the framing right prevents the response from going off course. The goal is to "check this high-probability, self-inspectable area first," not to conclude that "the log database is always to blame." Links to the full issues are in the references section at the end.

What Does logs_2.sqlite Actually Store?

logs_2.sqlite is the local SQLite log database used by Codex Desktop. Think of it as an operational record: diagnostic data the program writes as it runs. It is not your work log, not a Skills file, not a memory store, and not an output folder.

What Gets Recorded

Timestamps, log levels, targets, error messages, tracing spans, connection and tool execution states, and other diagnostic data the program needs to retain while running.

What It Should Not Be Used For

It is not a place for your own notes, and it is not suitable as a long-term storage location for finished work. Task conclusions, deliverables, and Skills should be saved as your own files.

Do Not Share the Raw File

The log may contain local paths, error fragments, tool call summaries, or information about your working environment. Cleaning and backing it up is fine. Sending the raw database around is not recommended.

Looking through the repo, several related reports emerged: some users found that moving logs_2.sqlite* out of the way caused Codex to rebuild the log database from scratch. Others reported issues caused by WAL files, TRACE-level logs, or database corruption. This suggests the file has a life of its own and is worth treating as a local database that can grow over time, not something you can safely ignore indefinitely.

What to Do When Things Break

Two paths, depending on your situation. If you're comfortable with terminal commands or have Claude Code installed, take Path A, the conservative full sequence. If you're newer to this, Path B's three steps are enough.

Path A: You're Comfortable with Commands, or You Have Claude Code

If you can work with the terminal or have Claude Code available, ask Claude Code to follow the conservative sequence below. The goal is to preserve the current state first, then let Codex rebuild the log state it can rebuild. Every step follows the same principle: back up before touching anything.

Step 1

Fully close Codex before doing anything. Touching the database while it's still writing is risky.

Step 2

Back up ~/.codex/logs_2.sqlite, logs_2.sqlite-wal, and logs_2.sqlite-shm. Keep copies of all three before proceeding.

Step 3

Check the sizes of the main file, WAL, and SHM, then run a SQLite quick_check. If the database is healthy and not oversized, just report the status. Do not force a cleanup.

Step 4

If the main file is oversized, the WAL is oversized, the row count is abnormal, or quick_check fails, confirm that a full backup exists first. Then retain only the last 48 hours of logs and run checkpoint, VACUUM, and PRAGMA optimize.

Step 5

If safe cleanup still isn't possible, move logs_2.sqlite* to a backup folder and let Codex rebuild the log database. Back up before this step too. Do not delete the files directly.

Step 6

If Codex still won't start after all of the above, then consider uninstalling and reinstalling. After reinstalling, set up the automated health check described in the next section immediately.

Stop Immediately If You See Any of These If you encounter "database locked," "Operation not permitted," or any SQLite error, stop and do not force-delete files. Also, do not delete the WAL while Codex is still running. Issues in the repo warn that a running process may still hold old file descriptors, and force-deleting or truncating a live WAL can cause new crashes or corrupt the database further.

Path B: You're New to This, Follow These Three Steps

If the commands feel overwhelming, skip them. Three steps is all you need to remember.

Step 1

Reinstall Codex directly. Accept that local tasks may be lost in the process. In this situation, getting Codex back online is the priority.

Step 2

Once it restarts, don't rush into a new task. Opening a new task immediately means logs start accumulating again, and the database may overflow quickly and crash again. The very first thing after a successful restart is to clear the logs.

Step 3

After clearing the logs, set up the automated health check described in the next section. It will run regular inspections going forward so you're unlikely to need a reinstall again.

How to Choose Between the Two Paths If you're comfortable with commands or have Claude Code on hand, take Path A. You'll be able to preserve more of your current state. If you're stuck and don't want to research the commands, take Path B. Reinstall first to get the tool back, then clear the logs and set up the automated check to prevent a recurrence.
One-page summary of the Codex log health check workflow: six steps on the left, actual crash screenshots and key takeaways on the right
The full workflow at a glance: the left side shows six steps from closing Codex through backup, inspection, and setting up routine checks. The right side closes with the core message: logs can be cleared, but your tasks and work belong in your own files.

Preventing the Problem: Let Codex Run Its Own Health Check

Waiting for a crash to act is more expensive than running regular checks. If you use Codex every day, running the check every three to five days is a reasonable rhythm. Personally, I run it Tuesday and Friday mornings. If you use Codex occasionally, once a week is enough.

Heavy Daily Use

Check every three to five days. My personal preference is Tuesday and Friday. Suggested thresholds for triggering maintenance: main file over 300MB, WAL over 100MB, row count over 120,000, or a failed quick_check.

Occasional Use

Once a week is sufficient. The goal is consistent inspection, not daily cleaning. When an issue is found, confirm the backup exists before taking any action.

The Safety Boundary for Automation The automated routine defaults to inspect-only mode. It reports, it does not clean. When a maintenance threshold is reached, it must stop, output a "maintenance handoff prompt," and remind you to fully close Codex Desktop first. Only after Codex is closed should you use that handoff prompt to handle the WAL and run VACUUM. Never touch a log database that is actively being written to.

Open a New Codex Conversation and Paste This Prompt

The safety boundaries above are baked into the prompt: inspect only, no cleanup unless triggered, report and produce a handoff prompt when thresholds are met, stop immediately when uncertain. Before pasting, replace the username in the paths with your own, or ask Codex to detect and substitute the current machine's paths automatically.

Please help me set up a Codex log health check automation. Goal: Run every 3 to 5 days (Taiwan time) to inspect the health of the local Codex Desktop log database. Default mode: inspect and report only. Do not run maintenance automatically. Files to check: /Users/your-username/.codex/logs_2.sqlite /Users/your-username/.codex/logs_2.sqlite-wal /Users/your-username/.codex/logs_2.sqlite-shm Restrictions: Do not read or output the full log body. Do not touch sessions, memories, skills, the main knowledge base, or any conversation records. Report only: file sizes, row count, time range, ERROR count from the past 24 hours, quick_check result, and whether maintenance is needed. Maintenance thresholds: If quick_check is not "ok", or the main file exceeds 300MB, or the WAL exceeds 100MB, or the row count exceeds 120,000: report that maintenance is needed. Do not clean immediately. Do not run VACUUM. When maintenance is needed: 1. Report the trigger reason. 2. Report current size, row count, time range, and ERROR count. 3. Output a "maintenance handoff prompt" reminding the user to fully close Codex Desktop first. 4. Stop this health check run. Do not proceed with maintenance. The maintenance handoff prompt must include: 1. Create the backup folder: /Users/your-username/.codex/sqlite/log-maintenance/ 2. Back up logs_2.sqlite, logs_2.sqlite-wal, and logs_2.sqlite-shm to: /Users/your-username/.codex/sqlite/log-maintenance/ Backup filenames must include YYYY-MM-DD-HHMM. 3. Confirm backup files exist and are larger than 0 bytes. 4. Retain only the last 48 hours of logs. 5. Run wal_checkpoint(TRUNCATE). 6. Run VACUUM. 7. Run PRAGMA optimize. 8. Run quick_check again. 9. Report before/after size, retained row count, retained time range, backup path, and schedule rule. Safety boundary: If you encounter "database locked", "Operation not permitted", any SQLite error, or anything uncertain: stop immediately. Do not force-delete files. Report what blocked you.
A Note from Mika If you don't know your username, just ask Codex to detect it. It will substitute the correct path for /Users/your-username/ automatically. Please don't modify hidden folders on your own, and don't delete the entire .codex folder.

How to Keep Your Work Safe When Tools Break

The real lesson from this incident is not to treat Codex's local state as your only storage location. Tools get updated, break, and get reinstalled. Your knowledge assets need to be protected by your own habits. Here are the three things I rely on.

Write a Work Log After Each Task

When a task wraps up, write down what you did, where the output lives, what problems came up, and what the next step is. Save it as your own work log.

Save Outputs to Your Own Folders

Articles, images, slides, code, prompts, reports: all of these should be saved as files in a location you can find. Don't leave them only inside a conversation.

Turn Good Workflows into Skills

If a process is worth repeating, write it up as a Skills file or SOP. When Codex breaks, Claude, another agent, or your next machine can still read and pick it up.

With these three habits in place, if Codex ever goes down completely, the situation is just a tool switching problem. Your work context is still intact. You're not starting from zero.

Thirty-Second Recap

  • When Codex Desktop won't open, updates don't help, and a reinstall is the last resort: check logs_2.sqlite first after reinstalling.
  • The evidence comes from related issues and source code in the OpenAI Codex GitHub repo. It is one plausible cause worth checking first, not the only possible explanation for every crash.
  • Two paths: if you're comfortable with commands or have Claude Code, use the conservative sequence (close Codex, back up all three log files, run quick_check, don't force cleanup when healthy, only do maintenance after confirming backups, stop immediately on lock or permission errors). If you're newer, reinstall, clear the logs before starting any new task, then set up the automated check.
  • Set up an automated health check to run every three to five days, in inspect-only mode by default. When thresholds are reached, output a maintenance handoff prompt and wait for Codex to be closed before proceeding.
  • Write a work log after each task. Save outputs to your own files. Turn reliable workflows into Skills.
A Note on Perspective Knowing how to clear logs and set up a health check is basic maintenance, not an advanced skill. There are plenty of people in this community who understand SQLite far better than I do. What actually compounds over time is the habit of keeping your own data: task context, outputs, and workflows in your own hands. When a tool breaks, it's just a tool breaking. Your work doesn't go down with it.

References: Issues and Source Code

Everything below comes from the OpenAI Codex GitHub repo, not from any official OpenAI announcement. These issues point to risks including an oversized log SQLite database, WAL anomalies, a corrupt log database, or high-volume TRACE log writes, all of which support the judgment that logs_2.sqlite is worth checking first.

The One Line That Matters

Logs can be cleared. Your tasks and work belong in your own files. Build the log health check, the automated inspection, the work log habit, and the Skills practice. When a tool breaks, it's just a tool breaking. Your work context stays with you.

Next StepOpen a new Codex conversation and paste the automation prompt above. After it runs, confirm that it reports file sizes, the quick_check result, whether maintenance thresholds were reached, and the schedule rule. If maintenance is needed, let it produce the handoff prompt first, then close Codex before acting on it. Do not clean inside the health check automation itself.
Free Online Talks

Two free talks every month.

Join the LINE Community ↗