Skip to main content

Runbook: User Studio Database Connection Issues

Symptoms​

  • Application shows "Application error: a server-side error has occurred"
  • Container logs show: TypeError: Cannot read properties of undefined (reading 'searchParams')
  • Stack trace points to pg-connection-string library

Root Cause​

The pg library uses JavaScript's native URL parser to parse PostgreSQL connection strings. If the password contains special characters that aren't URL-encoded, the parser fails with misleading error messages.

Common problematic characters:

  • / (forward slash) - interpreted as path separator
  • = (equals) - interpreted as query parameter
  • @ (at sign) - interpreted as user/host separator
  • # (hash) - interpreted as fragment
  • ? (question mark) - interpreted as query start

Diagnosis​

  1. Check container logs for the specific error:
ssh ravenhelm@100.115.101.81 "docker logs agent-studio --tail 50"
  1. Look for stack trace containing:
at parse (/app/node_modules/.pnpm/pg-connection-string@.../node_modules/pg-connection-string/index.js:39:30)
at new ConnectionParameters
  1. Verify DATABASE_URL is set:
ssh ravenhelm@100.115.101.81 "docker exec agent-studio printenv DATABASE_URL"

Resolution​

Step 1: Identify special characters in password​

Check the current DATABASE_URL:

ssh ravenhelm@100.115.101.81 "grep '^DATABASE_URL=' ~/ravenhelm/secrets/.env"

Step 2: URL-encode the password​

Use Python to encode the password:

python3 -c "import urllib.parse; print(urllib.parse.quote('YOUR_PASSWORD_HERE', safe=''))"

Example:

Original: Ej1XKFzjM4XjORb6O9/yc1xHS/5gI9I9Y1bjcW20k64=
Encoded:  Ej1XKFzjM4XjORb6O9%2Fyc1xHS%2F5gI9I9Y1bjcW20k64%3D

Step 3: Update the .env file​

ssh ravenhelm@100.115.101.81 "sed -i '' 's|DATABASE_URL=...|DATABASE_URL=postgresql://user:ENCODED_PASSWORD@host:5432/db|' ~/ravenhelm/secrets/.env"

Step 4: Restart the container​

ssh ravenhelm@100.115.101.81 "cd ~/ravenhelm/services/agent-studio && docker compose up -d studio"

Step 5: Verify​

curl https://studio.ravenhelm.dev/api/health

Prevention​

When generating database passwords:

  1. Avoid special characters if possible
  2. If using special characters, always URL-encode in connection strings
  3. Document encoded passwords in 1Password notes

Created: 2026-01-05 Category: Database, User Studio