diff --git a/cli/diagnose_db.php b/cli/diagnose_db.php
new file mode 100644
index 0000000..17662d8
--- /dev/null
+++ b/cli/diagnose_db.php
@@ -0,0 +1,49 @@
+<?php
+/**
+ * CLI: Print why the encrypted DB cannot be opened (deploy / env / permissions).
+ * Usage: php cli/diagnose_db.php
+ */
+if (php_sapi_name() !== 'cli') {
+    http_response_code(403);
+    echo "CLI only\n";
+    exit(1);
+}
+
+require_once __DIR__ . '/../common.php';
+require_once __DIR__ . '/../db_init.php';
+
+$envPath = __DIR__ . '/../.env';
+echo "Project: " . realpath(__DIR__ . '/..') . "\n";
+echo ".env: " . ($envPath && is_readable($envPath) ? "readable" : "MISSING or not readable") . "\n";
+
+$keyEnv = getenv('QDB_MASTER_KEY');
+if ($keyEnv === false || $keyEnv === '') {
+    echo "QDB_MASTER_KEY: NOT SET (set in .env or Apache/PHP-FPM env)\n";
+    exit(1);
+}
+echo "QDB_MASTER_KEY: set (" . strlen($keyEnv) . " chars)\n";
+
+$dbPath = QDB_PATH;
+$uploads = dirname($dbPath);
+echo "uploads dir: $uploads\n";
+echo "  exists: " . (is_dir($uploads) ? 'yes' : 'no') . "\n";
+echo "  writable: " . (is_writable($uploads) ? 'yes' : 'NO — migrations cannot save') . "\n";
+echo "DB file: $dbPath\n";
+echo "  exists: " . (is_file($dbPath) ? 'yes (' . filesize($dbPath) . ' bytes)' : 'no (will create on first write)') . "\n";
+
+try {
+    [$pdo, $tmpDb, $lockFp] = qdb_open(false);
+    $version = (int)$pdo->query('PRAGMA user_version')->fetchColumn();
+    $users = (int)$pdo->query('SELECT COUNT(*) FROM users')->fetchColumn();
+    $hasSession = qdb_table_exists($pdo, 'session');
+    qdb_discard($tmpDb, $lockFp);
+    echo "OK: database opened and decrypted.\n";
+    echo "  PRAGMA user_version: $version (expected " . QDB_VERSION . ")\n";
+    echo "  users: $users\n";
+    echo "  session table: " . ($hasSession ? 'yes' : 'MISSING') . "\n";
+    exit(0);
+} catch (Throwable $e) {
+    echo "FAILED: " . $e->getMessage() . "\n";
+    echo "  (Check Apache/PHP error_log for stack trace.)\n";
+    exit(1);
+}
diff --git a/db_init.php b/db_init.php
index ecf22be..1742902 100644
--- a/db_init.php
+++ b/db_init.php
@@ -94,6 +94,21 @@ function qdb_apply_migrations(PDO $pdo, string $schemaSql): bool {
         $changed = true;
     }
 
+    if (!qdb_table_exists($pdo, 'session')) {
+        $pdo->exec("
+            CREATE TABLE session (
+                token     TEXT    NOT NULL PRIMARY KEY,
+                userID    TEXT    NOT NULL,
+                role      TEXT    NOT NULL,
+                entityID  TEXT    NOT NULL DEFAULT '',
+                createdAt INTEGER NOT NULL,
+                expiresAt INTEGER NOT NULL,
+                temp      INTEGER NOT NULL DEFAULT 0
+            )
+        ");
+        $changed = true;
+    }
+
     if (qdb_table_exists($pdo, 'questionnaire_submission')) {
         require_once __DIR__ . '/lib/submissions.php';
         if (qdb_backfill_submissions_from_live($pdo)) {