ragtime debugging.instructions.md

Debugging

Start With Runtime Health

# API readiness + index loading status
curl -s http://localhost:8000/health | jq .

# Service logs
docker logs -f ragtime-dev
docker logs -f ragtime-db-dev

If /health shows status=initializing, check for startup failures in ragtime/main.py lifecycle (DB connect, rag.initialize(), index recovery/cleanup).

Database Access (Prisma/Postgres)

docker exec -i ragtime-db-dev bash -c \
  'PGPASSWORD="${POSTGRES_PASSWORD}" psql -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" -c "YOUR_QUERY"'

Useful tables: users, sessions, ldap_config, conversations, chat_tasks, index_jobs, index_metadata, index_configs, tool_configs, app_settings.

Prompt debug table (DEBUG mode only): provider_prompt_debug_records.

# Latest prompt-debug rows for one conversation
docker exec -i ragtime-db-dev bash -c \
  'PGPASSWORD="${POSTGRES_PASSWORD}" psql -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" \
   -c "select provider,model,mode,request_kind,created_at from provider_prompt_debug_records where conversation_id = '\''<conversation_id>'\'' order by created_at desc limit 20;"'

# Prompt-debug rows for a specific background task
docker exec -i ragtime-db-dev bash -c \
  'PGPASSWORD="${POSTGRES_PASSWORD}" psql -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" \
   -c "select provider,model,request_kind,created_at from provider_prompt_debug_records where chat_task_id = '\''<task_id>'\'' order by created_at asc;"'

# Compare userspace vs chat prompt payloads (prompt additions + reminders)
docker exec -i ragtime-db-dev bash -c \
  'PGPASSWORD="${POSTGRES_PASSWORD}" psql -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" \
   -c "select mode,left(turn_reminders,120) as reminders,left(prompt_additions,120) as additions,created_at from provider_prompt_debug_records where conversation_id = '\''<conversation_id>'\'' order by created_at desc limit 20;"'

Auth + Session Troubleshooting

# Detect cookie/security config mismatches
curl -s http://localhost:8000/auth/status | jq .

# Login and capture ragtime_session cookie value
TOKEN=$(docker exec ragtime-dev bash -lc 'curl -s -c - -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"$LOCAL_ADMIN_USER\",\"password\":\"$LOCAL_ADMIN_PASSWORD\"}" \
  | awk "/ragtime_session/ {print \\$NF}"')

# Authenticated admin endpoint smoke test
curl -s http://localhost:8000/indexes/jobs -H "Cookie: ragtime_session=$TOKEN" | jq .