Troubleshooting
Solutions to common issues with database connections, schema validation, and runtime execution in an5 ORM.
Active Context: Troubleshooting for Kotlin on Googlesheets.
Connection Issues
1. Connection Refused or Host Unreachable
Symptom: ECONNREFUSED, Connection refused, or timeout trying to open database connection.
Diagnostic Checklist:
- Confirm the database service is running on the host and port.
- Verify network firewalls allow incoming traffic from your application IP.
- Validate connection string syntax for Googlesheets:
# Valid connection format for Googlesheets
DATABASE_URL=googlesheets://spreadsheetId;clientEmail=sa@project.iam.gserviceaccount.com;privateKey=...
Google Sheets specific notes:
- If receiving
403 Forbidden, ensure the target Google Spreadsheet is shared with the service account email (clientEmail) with Editor permissions. - Ensure private key newlines (
\n) in.envare URL-encoded or preserved properly.
Connection Diagnostic Test
Run a quick connection health test using your active language:
Schema & Code Generation Issues
1. Type Mismatch in Schema
Error: Invalid field type 'X' for provider 'Y'
Cause: The schema .an5 uses a type specific to another database dialect (e.g. BIT on SQLite or BOOLEAN on SQL Server).
Solution: Align field types in an5Schema/ with the dialect rules of Googlesheets:
- Consult the Field Types reference for valid types per provider.
2. Output Directory Not Found
Error: Directory does not exist for generator output
Solution: an5Orm generates directories automatically. Ensure your user has filesystem write permissions in the workspace and verify outputs paths in an5Orm.config.js.
Next Steps
- Database Providers - Full dialect specifications
- Deployment - Production security and pooling setup