Fix Codex Database Errors: state_5.sqlite & Migration Issues

If you're seeing errors like "Codex cannot access its local database" or dealing with state_5.sqlite and migration issues, you're not alone. These are common problems in development and production environments, but fortunately, they're solvable with the right approach.

This comprehensive guide walks you through understanding these errors, diagnosing the root cause, and implementing solutions that work. Whether you're a developer, DevOps engineer, or system administrator, you'll find actionable steps to get your Codex instance back online quickly.

Important: Always backup your database files before attempting any fixes. Corrupted or inaccessible databases require careful handling.

Understanding "Codex Cannot Access Its Local Database"

What Does This Error Mean?

This error occurs when Codex cannot establish a connection to its local SQLite database. The database file exists, but the application cannot read from it or write to it due to various reasons:

• File permissions issues — The application doesn't have read/write access
• Database corruption — The SQLite file is damaged or incomplete
• File locking — Another process has locked the database
• Disk space problems — No space available to write data
• Path issues — Database file path is incorrect or inaccessible
• Migration failures — Database schema is inconsistent

Where Does This Error Appear?

You typically see this error in:

• Application startup logs
• Error console or terminal output
• Browser console (network errors)
• System event logs

Understanding state_5.sqlite

What is state_5.sqlite?

state_5.sqlite is a SQLite database file used by Codex to store application state, configuration, and metadata. The "5" indicates the schema version. This file tracks:

Why Does state_5.sqlite Fail?

Several factors can cause this file to fail:

• Incomplete writes — Process crashed during database write operation
• Disk errors — Physical disk problems corrupted the file
• Permission changes — File permissions were altered after creation
• Version mismatch — Application version incompatible with database schema
• Concurrent access — Multiple processes accessing simultaneously without proper locking

Migration Errors Explained

What Are Database Migrations?

Migrations are versioned changes to your database schema. Each migration represents an update like adding tables, columns, or indexes. Codex tracks which migrations have been applied to your database to prevent duplicate applications.

Error: "Migration 1 Was Previously Applied But Has Been Modified"

This error occurs when:

• Migration file changed — You modified a migration file after it was already applied
• Rollback conflict — A migration was partially rolled back and then changed
• Sync issues — Database state doesn't match migration history
• Version control conflicts — Merge conflicts in migration files weren't resolved properly

Never modify migration files after they're applied to production. This breaks the integrity of your database schema and creates inconsistencies that are difficult to repair.

Quick Fixes & Solutions

Solution 1: Check File Permissions

File permissions are often the culprit. The application needs read and write access to the database file.

On Linux/macOS:

Check current permissions
ls -la state_5.sqlite

Fix permissions (give read/write access to the user running Codex)
chmod 644 state_5.sqlite
chmod 755 $(dirname state_5.sqlite)

If running as specific user, change ownership
chown codex:codex state_5.sqlite

On Windows (PowerShell):

Check current user has access to the file
icacls state_5.sqlite

Grant full permissions to current user
icacls state_5.sqlite /grant %username%:F

This is often the first and easiest fix. Many database access errors are simply permission problems. If you recently changed users or moved the database file, permissions are usually the issue.

Solution 2: Clear File Locks

If another process has locked the database, you need to clear those locks before you can access it.

Restart the application — This cleanly closes all database connections. This is the safest and most recommended approach.

Kill lingering processes — If restarting doesn't work, find and terminate processes accessing the file:

Find processes accessing the database
lsof | grep state_5.sqlite

Kill the process (replace PID with actual process ID)
kill -9 PID

Delete lock files — SQLite creates temporary files during operations. Remove them:

Remove WAL (Write-Ahead Logging) files
rm state_5.sqlite-shm state_5.sqlite-wal

The .shm (shared memory) and .wal (Write-Ahead Log) files are temporary files used by SQLite for transaction management. They're created during active database operations and should be cleaned up automatically when closed, but sometimes they persist and cause issues.

Solution 3: Check Disk Space

Databases cannot grow if there's no disk space available. This is a common but often overlooked cause of database errors.

Check available disk space
df -h

If disk is full, find what's using space
du -sh ./* | sort -hr | head -20

Ensure at least 10% free disk space for database operations to proceed smoothly. If your disk is over 90% full, start cleaning up immediately. Consider archiving old logs or temporary files.

Solution 4: Backup and Recreate Database

If the database is corrupted beyond repair, you may need to recreate it. This should be your last resort because you'll lose all data in the corrupted database.

Step 1: Backup the corrupted file
cp state_5.sqlite state_5.sqlite.backup

Step 2: Remove the corrupted database
rm state_5.sqlite

Step 3: Restart Codex (it will recreate the database automatically)
systemctl restart codex
or whatever command starts your Codex instance

Step 4: Re-apply migrations if needed
codex migrate up

This works only if you don't need the data in the corrupted database. For production environments, always have backups before attempting this.

Solution 5: Fix Migration Conflicts

If you see "migration was previously applied but has been modified", follow these steps carefully:

Step 1: Identify the modified migration

codex migrate status

This shows you which migrations were applied and which are causing issues.

Step 2: Revert the changes to the migration file

Use git to restore the original version:

git checkout migrations/migration_name.sql

Step 3: If changes are necessary, create a new migration

Never modify existing migrations. Instead, create a new one:

codex migrate create fix_schema

Edit the new migration file with your changes

codex migrate up

Step 4: Update migration history if out of sync

Reset migration history (only in development!):

codex migrate reset

codex migrate up

Warning: migrate reset destroys all data. Only use in development environments. Never run this in production.

Advanced Troubleshooting

Validate Database Integrity

SQLite has built-in tools to check if your database is corrupted:

sqlite3 state_5.sqlite "PRAGMA integrity_check;"

If output is "ok", database is healthy. If corrupted, you'll see error messages describing the issues.

Examine Migration History

Query the migrations table directly to see which migrations were applied:

sqlite3 state_5.sqlite "SELECT * FROM migrations ORDER BY id DESC LIMIT 20;"

This shows which migrations were applied and when. Compare this with your migration files to identify conflicts.

Check Database Schema

View the actual database structure:

sqlite3 state_5.sqlite ".schema"

This lists all tables and their structure. Compare with expected schema to identify mismatches between what should be there and what actually is.

Enable Debug Logging

To get more detailed error information, enable debug mode:

Set environment variable:

export DEBUG=codex:*

Or in .env file:

DEBUG=codex:database

Restart application:

codex start

Debug logging reveals exactly where the problem occurs and provides detailed context for each operation.

Analyze Application Logs

Check detailed logs for specific error messages:

• EACCES — Permission denied error
• EAGAIN — Resource temporarily unavailable (lock timeout)
• ENOSPC — No space left on device
• CORRUPTION — Database integrity issues

Look for these specific error codes in your logs to pinpoint the exact problem.

Prevention Best Practices

1. Implement Regular Backups

Automate daily backups of your state database so you can recover if something goes wrong:

• Use cron jobs (Linux/macOS) or Task Scheduler (Windows) for automation
• Backup to cloud storage (S3, Azure, Google Cloud) for safety
• Maintain versioned backups (daily, weekly, monthly)
• Test restoration procedures regularly to ensure backups work

A good backup strategy is your safety net. When disasters happen, backups are what save you.

2. Monitor Disk Space

Prevent disk space issues before they cause problems:

• Set up alerts when disk usage exceeds 80%
• Implement log rotation to prevent unbounded growth
• Archive old data periodically
• Clean up temporary files automatically

3. Version Control Migrations

Manage migrations safely:

• Never modify applied migrations — create new ones instead
• Review migration files in code reviews before applying
• Test migrations in staging before production deployment
• Keep detailed migration notes in commit messages

4. Database Maintenance

Run periodic maintenance commands to keep database healthy:

Optimize database
sqlite3 state_5.sqlite "VACUUM;"

Analyze query performance
sqlite3 state_5.sqlite "ANALYZE;"

Rebuild indexes
sqlite3 state_5.sqlite "REINDEX;"

5. Implement Proper Access Controls

Secure your database files:

• Ensure correct file ownership and permissions
• Restrict database access to application user only
• Use principle of least privilege
• Monitor for unauthorized access attempts

6. Use Environment-Specific Configurations

Avoid mixing environments:

• Keep development, staging, and production databases separate
• Use different database paths for each environment
• Never share production database files with other environments

Conclusion

Database errors like "Codex cannot access its local database" and migration conflicts are frustrating, but they're preventable and fixable with the right approach. By understanding the root causes, implementing the solutions in this guide, and following best practices, you can maintain a healthy, reliable Codex instance.

Key takeaways:

• Always backup before attempting fixes
• Check permissions and disk space first
• Never modify applied migrations
• Test migrations in staging before production
• Monitor disk usage and database health proactively

If you continue experiencing issues after following this guide, consider enabling debug logging and consulting the Codex documentation or community forums. Include detailed error messages and logs to help others diagnose your specific situation.

Ready to proceed? Start with Solution 1 (permissions check) and work through the fixes in order. Most issues resolve within the first 2-3 solutions.

Frequently Asked Questions

Related guide: For the quick fix, see Codex cannot access its local database — how to fix it.