Technical Troubleshooting

This article covers technical issues that may require coordination with your system administrator or IT team. It includes solutions for authentication errors, session problems, and infrastructure issues.

Authentication Issues

"Unauthorized" Page

Symptoms: You are redirected to an "Unauthorized" page after trying to access the application.

Causes:

• Your JWT authentication token has expired.
• The automatic token refresh failed.
• Your session has been invalidated.

Solutions:

1. Refresh the page -- The application attempts automatic JWT refresh on the first 401 error. A page refresh triggers this process.
2. Re-login from the main platform -- Navigate to the Kinderpedia main application and log in again. Then re-open the admissions module.
3. Clear cookies -- Clear the JWToken cookie and reload. This forces a fresh authentication.
4. Check the auth gateway -- If the issue persists, the auth gateway service may be down. Contact your system administrator.

Session Keeps Expiring

Symptoms: You are frequently logged out or see authentication errors.

Possible causes:

1. Short token lifetime -- JWT tokens have a fixed expiry. The system should auto-refresh them, but network issues can interrupt this.
2. Multiple tabs -- Having the application open in many tabs can cause concurrent refresh attempts that interfere with each other.
3. Network interruptions -- Unstable internet connections may prevent successful token refresh.

Solutions:

• Close extra browser tabs with the application open.
• Ensure your internet connection is stable.
• Contact your administrator if the token lifetime needs adjustment.

"Access Denied" Errors

Symptoms: You can log in but cannot access certain pages or perform certain actions.

Solutions:

1. Check your assigned roles in Configuration > Users & Roles.
2. Verify you have the required permissions for the action (see Access Control).
3. Ask an administrator to review and update your role assignments.

SSL / Certificate Issues

Browser Shows "Not Secure" Warning

For local development environments:

• The local development setup uses self-signed SSL certificates.
• Open https://crm-local.kinderpedia.co:8467 directly in the browser.
• Accept the self-signed certificate warning.
• Reload the application.

For production:

• SSL certificates should be managed by the infrastructure team.
• If you see SSL warnings in production, contact your system administrator immediately.

Mixed Content Warnings

Symptoms: Some resources fail to load with "Mixed Content" errors in the browser console.

Solutions:

• Ensure all resource URLs use HTTPS, not HTTP.
• Check CDN and S3 URLs for correct protocol.
• Contact your Kinderpedia administrator to verify the CDN and storage URLs are served over HTTPS.

Iframe Communication Issues

Application Not Loading Inside Kinderpedia

Symptoms: The admissions module shows a blank page or loading spinner when accessed through the Kinderpedia main application.

Causes:

• The iframe PostMessage handshake may have failed.
• The school ID was not properly transmitted.

Solutions:

1. Refresh the parent page -- Reload the Kinderpedia main application page.
2. Check browser console -- Look for PostMessage errors or CSP (Content Security Policy) violations.
3. Verify frame-ancestors -- The X_FRAME_ALLOW_ORIGIN_FROM environment variable must include the parent domain.

School ID Not Set

Symptoms: API requests fail with missing school ID errors. Data does not load.

Solutions:

1. The school ID is transmitted via PostMessage from the parent iframe.
2. If running outside the iframe (development), set dev_kindergarten_id in localStorage.
3. Refresh the page to re-trigger the PostMessage flow.

Data Loading Issues

Blank Pages or Missing Data

Symptoms: Pages load but show no data, or show loading spinners indefinitely.

Solutions:

1. Check the browser console -- Look for API errors (4xx or 5xx responses).
2. Check network connectivity -- Ensure the API server is reachable.
3. Clear browser cache -- Stale cached data can cause issues. Clear cache and reload.
4. Check school context -- Ensure the correct school ID is set (see above).

"500 Internal Server Error"

Symptoms: API calls return 500 errors.

Solutions:

1. This indicates a server-side error. Contact your system administrator.
2. Check if the issue is specific to one page/action or affects the entire application.
3. The server logs will contain the detailed error information.

File Upload Issues

Upload Fails or Times Out

Symptoms: File uploads (logos, form attachments, signed contracts) fail.

Solutions:

1. Check file size -- Maximum upload size is 10MB.
2. Check file type -- Allowed types: jpg, jpeg, png, gif, webp, avif, heic, heif, pdf, csv, xlsx, xls, doc, docx.
3. Storage configuration issue -- If the issue persists across files and types, contact your Kinderpedia administrator.
4. Try a smaller file -- If the file is near the size limit, try compressing it.

Downloaded Files Are Expired

Symptoms: Clicking a download link shows an "Access Denied" or "Link Expired" error.

Solutions:

• Private files use presigned URLs that expire after 15 minutes.
• Navigate back to the record and generate a new download link.
• Download files promptly after generating the link.

Getting Further Help

If the solutions above do not resolve your issue:

1. Note the exact error message, page URL, and steps to reproduce.
2. Take a screenshot of the browser console (press F12 to open).
3. Contact your system administrator with these details.
4. See Getting Help for support contact information.

Was this helpful?