Codegen Troubleshooting

Purpose: Common issues and solutions
Last Updated: 2024-11-28

Quick Fixes

Problem	Solution	Command
Type errors	Regenerate code	pnpm db:codegen
Missing function	Check schema included	pnpm db:codegen --verbose
Validation error	Check parameter types	See error message
Stale types	Force regeneration	pnpm db:codegen --force
IDE not updating	Restart TS server	Cmd/Ctrl + Shift + P → "Restart TS Server"

Connection Issues

Cannot Connect to Database

Symptoms:

Error: Connection refused
ECONNREFUSED 127.0.0.1:54320

Solutions:

1. Check database is running:

docker ps | grep postgres

2. Start database if not running:

docker compose up -d postgres

3. Verify connection string:

echo $DATABASE_URL

4. Test connection directly:

psql -h localhost -p 54320 -U savvi -d savvi_studio -c "SELECT 1"

Wrong Database

Symptoms:

Error: relation "my_schema.my_function" does not exist

Solutions:

1. Check you're connected to correct database
2. Verify schema loaded
3. Reset database if needed:

pnpm db:reset

Generation Issues

Function Not Generated

Symptoms: Function exists in database but not in generated code

Solutions:

1. Verify function exists in database
2. Check schema filter
3. Force regeneration:

rm -rf src/__generated__/my_schema
pnpm db:codegen

Type Not Generated

Symptoms: Custom type exists but schema not generated

Solutions:

1. Verify type exists in database
2. Check type category (must be enum, composite, or domain)
3. Verify schema loaded

Circular Dependency Error

Symptoms:

Error: Circular dependency detected: TypeA -> TypeB -> TypeA

Solution: Generated code handles circular refs automatically using z.lazy(). If you see this error, it's likely a bug in the codegen system.

Import Issues

Module Not Found

Symptoms:

Error: Cannot find module '@db/my_schema'

Solutions:

1. Restart TypeScript server (VS Code: Cmd/Ctrl + Shift + P → "Restart TS Server")
2. Verify path alias in tsconfig.json
3. Check generated files exist
4. Regenerate if missing:

pnpm db:codegen

Wrong Import Path

Symptoms:

Error: Module '"@db/graph"' has no exported member 'myFunction'

Solutions:

1. Check function name (camelCase in TypeScript, e.g., create_resource → createResource)
2. Import from correct schema
3. Check exports in index file

Type Errors

Type Mismatch After Update

Symptoms:

Error: Type 'string' is not assignable to type 'bigint'

Solutions:

1. Regenerate types:

pnpm db:codegen

2. Find all call sites:

grep -r "myFunction" src/

3. Update function calls to match new signature

Missing Required Parameter

Symptoms:

Error: Property 'p_email' is missing in type

Solutions:

1. Add required parameter to function call
2. Check if parameter should be optional in SQL (add DEFAULT)

Validation Errors

ZodError at Runtime

Symptoms:

ZodError: Invalid input
[{ code: 'invalid_type', expected: 'string', received: 'number', path: ['p_email'] }]

Solutions:

1. Check error details to see which field failed
2. Verify param types match expected types
3. Check for null/undefined vs nullable fields

Unexpected Database Output

Symptoms:

ZodError: Database returned unexpected data

Solutions:

1. Regenerate to sync with current schema:

pnpm db:codegen

2. Verify function return type matches actual output
3. Test function directly in psql

Performance Issues

Slow Codegen

Symptoms: Codegen takes > 5 seconds

Solutions:

1. Generate specific schemas only:

pnpm db:codegen --schema graph

2. Use caching:

pnpm db:codegen --cache

3. Check database performance

Large Generated Files

Symptoms: Generated files > 1MB

Solutions:

1. Split large schemas into multiple smaller schemas
2. Review function count per schema

Build Issues

Generated Code Doesn't Compile

Symptoms:

Error: TS2322: Type 'unknown' is not assignable to type 'string'

Solutions:

1. Check TypeScript version (should be >= 4.7)
2. Verify Zod version (should be >= 3.0)
3. Clean and rebuild:

rm -rf src/__generated__
pnpm db:codegen
pnpm tsc --noEmit

Module Resolution Errors

Symptoms:

Error: Cannot resolve module specifier

Solutions:

1. Check tsconfig.json module resolution settings
2. Restart development server
3. Verify path aliases configured correctly

Testing Issues

Mock Client Not Working

Symptoms: Tests fail with "query is not a function"

Solution: Ensure mock client has proper structure with query method.

Integration Tests Failing

Symptoms: Tests work locally but fail in CI

Solutions:

1. Check test database setup in CI config
2. Ensure database is ready before running tests
3. Run migrations before tests
4. Generate code in CI pipeline

Getting More Help

Enable Verbose Logging

pnpm db:codegen --verbose

Check Codegen Logs

# Review introspection queries
pnpm db:codegen --verbose 2>&1 | grep "SELECT"

# Review generated files
pnpm db:codegen --verbose 2>&1 | grep "Writing"

Report Issues

Include in bug reports:

1. PostgreSQL version
2. Node.js version
3. Codegen command used
4. Error messages (full stack trace)
5. Relevant SQL definitions
6. Example of generated code (if applicable)

Detailed Examples

For detailed troubleshooting examples with code, see:

• Troubleshooting Examples - Code examples for common issues
• CLI Examples - Debugging commands and workflows

Related Documentation

• Usage - Running codegen
• Overview - System architecture
• Type System - Type mappings
• Function Wrappers - Using generated code

---

Pro Tip: Most issues are solved by regenerating code with pnpm db:codegen and restarting the TypeScript server.