Common Issues

Solutions for frequently encountered issues with the Neostra platform.

Authentication Issues

Cause: JWT token expired (180-minute TTL) or missing Authorization header.

Fix:

Re-authenticate via POST /api/v1/auth/signin
Ensure the header format is Authorization: Bearer YOUR_TOKEN
If using multi-tenant, ensure you completed the tenant selection step (POST /api/v1/auth/select-tenant)

# Re-authenticate
curl -X POST https://api.neostra.io/v1/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "your-password"}'

Cause: Your role lacks the required permission for the endpoint.

Fix: Check the @PreAuthorize requirement for the endpoint. Permissions use resource:action format (e.g., subject-requests:create). Contact your tenant administrator to update your role's permissions.

Cause: 2FA must be enabled at the tenant level via feature flags before individual users can set it up.

Fix: Ensure TenantSetting.featureGroups has 2FA enabled. Then call POST /api/v1/auth/2fa/setup to generate the QR code.

CORS Issues

Cause: Your frontend domain is not in the allowed origins list.

Fix: Add your domain to the cors.origins property in the neostra-core configuration. The backend dynamically reads allowed origins from this property.

For local development, ensure http://localhost:5173 (default Vite port) is included.

Database Issues

Cause: MongoDB not running or incorrect connection string.

Fix:

Verify MongoDB is running: mongosh --eval "db.runCommand({ping: 1})"
Check MONGODB_URI environment variable (default: mongodb://localhost:27017)
Check MONGODB_DATABASE (default: dpdp)

Cause: Flyway or Liquibase migration conflicts.

Fix:

CPMP services use Flyway. Check the flyway_schema_history table for failed migrations.
Data Discovery uses Liquibase. Check databasechangelog table.
Ensure the database user has DDL permissions.

Service Connectivity

Cause: cpmp-api-service cannot reach Google Cloud Pub/Sub.

Fix:

Verify Pub/Sub topic cpmp-consent-topic exists
Check GCP credentials and project ID
For local development, use the Pub/Sub emulator

Cause: Selenium Grid not running or Chrome nodes unavailable.

Fix:

Verify Selenium Hub at http://localhost:4444
Ensure Chrome nodes are registered
Check cpmp-crawler-service logs for connection errors
Use GET /api/v1/diagnostic/selenium-hub to test connectivity

Cause: Python scanner worker not polling or database credentials incorrect.

Fix:

Verify the scanner is running and polling (check POLL_SECONDS config)
Check JDBC_URL, JDBC_USERNAME, JDBC_PASSWORD environment variables
Verify CRYPTO_SECRET_KEY and CRYPTO_SECRET_SALT for credential decryption

Was this page helpful?

Last updated Mar 16, 2026

Built with Documentation.AI