Troubleshooting

Solutions to common issues with database connections, schema validation, and runtime execution in an5 ORM.

Active Context: Troubleshooting for Typescript on Googlesheets.

Connection Issues

1. Connection Refused or Host Unreachable

Symptom: ECONNREFUSED, Connection refused, or timeout trying to open database connection.

Diagnostic Checklist:

  1. Confirm the database service is running on the host and port.
  2. Verify network firewalls allow incoming traffic from your application IP.
  3. 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 .env are URL-encoded or preserved properly.

Connection Diagnostic Test

Run a quick connection health test using your active language:

import { createAn5Adapter } from '@an5/adapters';

const db = createAn5Adapter({
  connectionString: process.env.DATABASE_URL!,
});

try {
  await db.$connect();
  console.log('Connected successfully to Googlesheets');
  await db.$disconnect();
} catch (error) {
  console.error('Connection failed:', error);
}

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