Chapter 21: Troubleshooting & FAQ

Issue: Node.js Version Conflicts

Symptoms: npm install fails with errors about unsupported engine or incompatible Node.js version.

Required Version: Node.js 18.17.0 or higher (LTS recommended). The project specifies this in package.json under the engines field.

Resolution:

1. Check your current Node.js version: node --version
2. If below 18.17.0, install the correct version using nvm: nvm install 18 nvm use 18 nvm alias default 18
3. Delete node_modules and package-lock.json, then run npm install again.

Issue: Dependency Installation Errors

Symptoms: npm install fails with peer dependency conflicts, ERESOLVE errors, or compilation errors for native modules.

Resolution:

1. Try installing with the legacy peer dependency resolution: npm install --legacy-peer-deps
2. If specific native modules fail to compile (e.g., sharp, bcrypt), ensure you have the required build tools installed:
   • macOS: xcode-select --install
   • Windows: Install Visual Studio Build Tools with the "Desktop development with C++" workload.
   • Linux: sudo apt-get install build-essential python3
3. Clear the npm cache: npm cache clean --force
4. Delete node_modules, package-lock.json, and .next folder, then reinstall.

Issue: Python Service Dependency Errors

Symptoms: Python service fails to start due to missing modules or incompatible package versions.

Required Version: Python 3.10 or higher.

Resolution:

1. Verify Python version: python3 --version
2. Create a virtual environment: python3 -m venv venv && source venv/bin/activate
3. Install dependencies: pip install -r requirements.txt
4. If psycopg2 fails to install, try the binary package instead: pip install psycopg2-binary
5. If reportlab or pandas fail, ensure you have the required system libraries:
   • macOS: brew install freetype libpng
   • Linux: sudo apt-get install libfreetype6-dev libpng-dev

Issue: PHP Integration Service Errors

Symptoms: PHP Laravel service fails to start, or composer install fails.

Required Version: PHP 8.1 or higher with extensions: pdo_pgsql, mbstring, openssl, curl, xml.

Resolution:

1. Verify PHP version and extensions: php -v and php -m
2. Install missing extensions (example for Ubuntu): sudo apt-get install php8.1-pgsql php8.1-mbstring php8.1-curl php8.1-xml
3. Run composer install and then php artisan key:generate
4. Copy .env.example to .env and configure database connection settings.
5. Run php artisan migrate to set up the required database tables.

Issue: Database Connection Failures

Symptoms: Application starts but displays "Database connection failed" or API requests return 500 errors with database-related messages.

Resolution:

1. Verify your .env.local file contains the correct Supabase / Oracle credentials: NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key SUPABASE_SERVICE_ROLE_KEY=your-service-role-key DATABASE_URL=postgresql://postgres:password@db.your-project.supabase.co:5432/postgres
2. Ensure the Supabase / Oracle project is running (check the Supabase / Oracle dashboard).
3. Verify your IP address is not blocked by Supabase / Oracle network restrictions (Settings > Database > Network Restrictions).
4. Test the database connection directly: psql "DATABASE_URL" -c "SELECT 1"
5. If using a connection pooler (PgBouncer), ensure you are using port 6543 instead of 5432.

Issue: Session Expired - Redirected to Login Unexpectedly

Symptoms: While using the application, you are suddenly redirected to the login page without warning, or you see a "Session expired" message.

Possible Causes:

1. The access token (60-minute lifespan) expired and the automatic refresh mechanism failed.
2. You were inactive for more than 30 minutes, triggering the inactivity timeout.
3. An administrator deactivated your account or changed your role while you were logged in.
4. Another device or browser session triggered a security event that revoked all sessions.
5. Browser privacy settings or extensions are blocking the cookie used to store the refresh token.

Resolution:

1. Log in again with your credentials. Your unsaved work may be lost.
2. Ensure your browser allows cookies from the NDSS CRM domain.
3. If this happens frequently, check with your administrator whether your account is being affected by a security policy.
4. Increase browser cookie permissions or add the NDSS CRM domain to your browser's cookie allowlist.

Issue: Password Reset Email Not Received

Symptoms: After clicking "Forgot Password" and entering your email, no reset email arrives.

Resolution:

1. Check your spam/junk folder. Search for emails from noreply@newdawnsupport.com.au.
2. Wait up to 5 minutes. Email delivery can be delayed.
3. Verify you are using the correct email address (the one registered in NDSS CRM, not a personal email).
4. Check with your IT department whether emails from newdawnsupport.com.au are being blocked by your organisation's email filter.
5. Contact your NDSS CRM administrator to manually reset your password through Admin > User Management.

Issue: Role Permissions Not Working After Role Change

Symptoms: An administrator changed your role, but you still see the old menu items and permissions.

Resolution:

1. Log out completely (click your avatar > Logout).
2. Clear your browser cache for the NDSS CRM domain.
3. Log back in. The new role and permissions should now be active.
4. If the issue persists, have the administrator verify the role change was saved successfully in Admin > User Management.

Issue: Slow Page Load Times

Symptoms: Pages take more than 3 seconds to load, especially list views (Clients, Staff, Shifts).

Resolution:

1. Reduce page size: Use the pagination controls to reduce the number of records per page. The default is 25; consider reducing to 10 for slower connections.
2. Apply filters: Use the filter controls to narrow the dataset before loading. For example, filter Clients by region or status instead of loading all records.
3. Check network speed: Run a speed test. NDSS CRM requires a minimum of 5 Mbps download speed for optimal performance.
4. Disable browser extensions: Extensions that inject scripts or modify network requests can significantly slow page loads.
5. Update your browser: Ensure you are using the latest version of Chrome, Firefox, Edge, or Safari.

Issue: Dashboard Loading Slowly

Symptoms: The dashboard takes a long time to load, particularly the KPI widgets and charts.

Resolution:

1. The dashboard aggregates data from multiple tables. During peak hours (9:00-10:00 AM AEST), there may be increased database load.
2. If the dashboard consistently loads slowly, contact your administrator to review the dashboard widget configuration. Some widgets (e.g., financial summaries, compliance scores) run complex queries that can be scheduled to pre-compute during off-peak hours.
3. Use the dashboard customisation feature to remove widgets you do not need, reducing the number of queries executed on page load.

Issue: Report Generation Timeout

Symptoms: Generating a report produces a timeout error or the report never completes.

Resolution:

1. Reduce the date range for the report. Reports covering more than 12 months of data may take longer to generate.
2. Apply additional filters (region, department, client group) to reduce the dataset.
3. For very large reports, use the "Schedule Report" option to generate the report in the background. You will receive an email notification when the report is ready for download.
4. If the issue persists, contact support. The Python report generation service may need resource scaling for your data volume.

Issue: Database Query Optimisation (Administrators)

Symptoms: Administrators notice slow query performance in the Supabase / Oracle dashboard.

Resolution:

1. Review the Supabase / Oracle query performance dashboard for slow queries exceeding 500ms.
2. Ensure database indexes are up to date. Run the index verification script: -- Check for missing indexes on frequently queried columns SELECT schemaname, tablename, indexname, indexdef FROM pg_indexes WHERE schemaname = 'public' ORDER BY tablename, indexname;
3. Run ANALYZE on heavily updated tables to refresh query planner statistics: ANALYZE clients; ANALYZE shifts; ANALYZE invoices; ANALYZE incidents;
4. Monitor connection pool utilisation. If the pool is consistently at capacity, contact Newdawn Support Services to upgrade the Supabase / Oracle plan.

Issue: Caching and Stale Data

Symptoms: Recently updated data is not visible, or old data continues to display after changes.

Resolution:

1. Press Ctrl + Shift + R (Windows) or Cmd + Shift + R (Mac) to perform a hard refresh.
2. NDSS CRM uses Supabase / Oracle Real-Time subscriptions for live data updates. If real-time is not working, check your browser's WebSocket connectivity by looking for wss:// connections in the Network tab of developer tools.
3. If the issue is specific to the Client Portal, note that portal data refreshes every 60 seconds rather than in real-time.
4. Clear the browser's local storage for the NDSS CRM domain: Developer Tools > Application > Local Storage > select domain > Clear All.

Issue: Bulk Import Errors

Symptoms: A CSV or XLSX import fails partially or completely, with error messages referencing specific rows.

Resolution:

1. Download the error report from the import status page (Admin > Data Import > History).
2. Review each error. Common issues include:
   • Invalid date format: Dates must be in YYYY-MM-DD format. Excel may auto-format dates. Save as CSV and verify the date format in a text editor.
   • Duplicate NDIS number: A client with the same NDIS number already exists. Either update the existing record or correct the NDIS number in the import file.
   • Missing required fields: Ensure all required columns are present and populated. Required fields for clients: firstName, lastName, dateOfBirth, ndisNumber, primaryDisability.
   • Invalid enum values: Fields like status, region, and gender must use the exact allowed values. Check the CSV template (Admin > Data Import > Download Template) for the complete list of valid values.
3. Fix the errors in the source file and re-import only the failed rows (use the "Skip duplicates" option).
4. For very large files (over 1,000 rows), consider splitting into smaller batches of 500 rows.

Issue: Duplicate Client or Staff Records

Symptoms: The same person appears multiple times in the client or staff list, causing confusion in rostering and invoicing.

Resolution:

1. Use the duplicate detection tool: Admin > Data Quality > Duplicate Detection. This tool scans for records with matching names, dates of birth, NDIS numbers, or email addresses.
2. Review the list of potential duplicates. The tool shows a match confidence score for each pair.
3. For confirmed duplicates, use the "Merge Records" function to combine two records into one. The merge process preserves all historical data (shifts, notes, invoices) from both records.
4. Only master_admin and administrator roles can merge records. The merge action is logged in the audit trail with a reference to both original record IDs.

Issue: Data Migration from Legacy System

Symptoms: Data imported from a legacy system has formatting issues, missing relationships, or incorrect field mappings.

Resolution:

1. Review the PHP integration connector documentation (Section 19.10) for supported legacy system connectors.
2. Use the "Dry Run" option before executing a full migration. This validates all records without committing changes to the database.
3. For custom legacy systems not covered by the built-in connectors, prepare data in the standard NDSS CRM CSV template format.
4. After migration, run the Data Integrity Check: Admin > Data Quality > Integrity Check. This verifies that all foreign key relationships are valid (e.g., every shift references a valid client and staff member).
5. Contact Newdawn Support Services for assistance with complex migrations involving more than 10,000 records or custom field mapping requirements.

Issue: API Authentication Errors (401)

Symptoms: API calls return 401 Unauthorized responses.

Resolution:

1. Verify the access token has not expired (tokens are valid for 60 minutes). Use the refresh endpoint to obtain a new token.
2. Ensure the Authorization header format is correct: Authorization: Bearer <token> (note the space between "Bearer" and the token).
3. Check that the token is being sent in the request header, not as a query parameter or in the request body.
4. If using a service account for automated integrations, verify the service account is still active in Admin > API Keys.

Issue: Webhook Delivery Failures

Symptoms: Webhooks are configured but the receiving system is not getting events, or the webhook status shows "Failed".

Resolution:

1. Check the webhook delivery log: Admin > Integrations > Webhooks > select webhook > Delivery History.
2. Review the HTTP response code from the receiving endpoint. Common issues:
   • Connection refused: The receiving server is not running or the URL is incorrect.
   • SSL certificate error: The receiving endpoint has an invalid or expired SSL certificate. NDSS CRM requires valid HTTPS endpoints for webhook delivery.
   • Timeout (30 seconds): The receiving endpoint is taking too long to respond. Webhooks must return a 2xx response within 30 seconds.
   • 403 Forbidden: The receiving server is rejecting the request. Verify the webhook secret is configured correctly on both sides.
3. Use the "Test Delivery" button to send a test event to the webhook URL and inspect the response.
4. After 50 consecutive failures, the webhook is automatically disabled. Re-enable it from the webhook configuration page after fixing the receiving endpoint.

Issue: Rate Limit Exceeded (429)

Symptoms: API calls return 429 Too Many Requests responses.

Resolution:

1. Review the X-RateLimit-Remaining and Retry-After response headers to understand your current usage and when the limit resets.
2. Implement exponential backoff in your integration code. When a 429 is received, wait for the number of seconds specified in the Retry-After header before retrying.
3. Optimise your integration to reduce the number of API calls. Use batch endpoints where available (e.g., POST /api/invoices/generate instead of creating invoices one by one).
4. If your integration legitimately requires higher limits, contact Newdawn Support Services to request a rate limit increase.