Troubleshooting

Common issues and solutions.

Login Issues

Cannot Log In

Symptoms: Login fails with "Invalid credentials"

Solutions:

1. Verify username and password are correct
2. Check Caps Lock is not on
3. Try resetting password
4. Contact IT if account may be locked

Session Expired

Symptoms: Redirected to login unexpectedly

Solutions:

1. Log in again -- sessions expire after 4 hours by default (12 hours maximum)
2. Check if you were inactive too long
3. Clear browser cache and cookies
4. If using multiple tabs, a logout in one tab invalidates the session everywhere

Access Denied

Symptoms: "You don't have permission" message

Solutions:

1. Verify you have the correct role
2. Contact administrator for access
3. Check if role assignment has expired

Registration Issues

Cannot Register for Course

Symptoms: "Unable to add course" error

Common Causes and Solutions:

Error	Cause	Solution
Hold on Account	Registration hold exists	Check holds and resolve
Prerequisite Not Met	Missing required course	Complete prerequisite or request override
Section Full	No seats available	Join waitlist or find another section
Time Conflict	Schedule overlap	Choose different section
Max Credits	Exceeds credit limit	Drop another course or request override
Not in Registration Window	Outside registration dates	Wait for your registration time

Hold Won't Clear

Symptoms: Hold still showing after resolution

Solutions:

1. Some holds require manual clearing
2. Contact the department that placed the hold
3. Allow time for processing (financial holds may take 24 hours)

Waitlist Issues

Symptoms: Not receiving waitlist notifications

Solutions:

1. Check spam/junk folder
2. Verify email address is correct
3. Ensure notification preferences are enabled
4. Monitor portal directly

Grade Issues

Grades Not Showing

Symptoms: Expected grades not appearing

Solutions:

1. Grades may not be posted yet - check deadline
2. Some holds block grade viewing
3. Contact instructor if past deadline

GPA Incorrect

Symptoms: GPA calculation seems wrong

Solutions:

1. Review GPA calculation rules
2. Check for repeat courses affecting GPA
3. Verify credit hours are correct
4. Contact Registrar for verification

Degree Audit Issues

Requirements Not Satisfied

Symptoms: Course not counting toward requirement

Solutions:

1. Course may not match requirement criteria
2. Grade may not meet minimum
3. May need substitution request
4. Contact advisor for review

Audit Not Loading

Symptoms: Degree audit shows error or won't load

Solutions:

1. Refresh the page
2. Try different browser
3. May be temporary system issue
4. Contact IT if persists

Billing Issues

Balance Incorrect

Symptoms: Account balance doesn't match expected

Solutions:

1. Review transaction history
2. Check for pending aid
3. Verify enrollment matches charges
4. Contact Student Accounts

Payment Not Reflected

Symptoms: Payment made but balance unchanged

Solutions:

1. Allow 1-2 business days for processing
2. Check payment confirmation
3. Contact Student Accounts with receipt

Technical Issues

Page Not Loading

Symptoms: Blank page or error message

Solutions:

1. Refresh the page
2. Clear browser cache
3. Try different browser
4. Check internet connection
5. System may be in maintenance

Data Not Saving

Symptoms: Changes not persisting

Solutions:

1. Check for validation errors
2. Ensure all required fields completed
3. Check internet connection
4. Try refreshing and re-entering

Slow Performance

Symptoms: System responding slowly

Solutions:

1. Check internet connection
2. Close unnecessary browser tabs
3. Try different browser
4. May be high system usage period

Browser Issues

Recommended Browsers

• Chrome (latest)
• Firefox (latest)
• Edge (latest)
• Safari (latest)

Common Browser Fixes

1. Clear cache and cookies
2. Disable browser extensions
3. Update browser to latest version
4. Try incognito/private mode

---

Common Developer Issues

Issues encountered when developing or running the SDASIS application locally.

Valkey/Redis Connection Required for Auth

Symptoms: Login fails immediately, or the backend logs show NOAUTH, connection refused, or dial tcp: connect: connection refused errors on startup.

Cause: The authentication system stores sessions in Valkey (Redis-compatible). There is no token blacklist — sessions are records that exist or do not. If Valkey is unreachable, session lookup fails and every authenticated request is rejected with 401. That is deliberate: authentication fails closed, so a cache outage cannot become a bypass.

Solutions:

1. Ensure Valkey or Redis is running locally on the configured port (default localhost:6379)
2. Check the .env values for REDIS_URL, REDIS_PASSWORD, and REDIS_DB
3. If using Docker: docker run -d --name valkey -p 6379:6379 valkey/valkey:latest
4. If Valkey is running but requires a password, set REDIS_PASSWORD in .env
5. If the container is running and the error is i/o timeout rather than connection refused, something else is holding the IPv6 loopback. On Windows, localhost resolves to ::1 before 127.0.0.1, and a stale wslrelay.exe can listen on [::1]:6379, accept the connection, and never answer — the dial succeeds, then the client's read times out. Diagnose with netstat -ano | findstr :6379 (look for two different PIDs) and set REDIS_URL=127.0.0.1:6379 to bypass it.

CSRF Token Mismatch

Symptoms: 403 Forbidden or "CSRF token mismatch" on POST/PUT/DELETE requests from the frontend.

Cause: The backend sets a CSRF token in a cookie, and the frontend must send it back in the X-CSRF-Token request header. A mismatch occurs when the cookie is missing, stale, or the header is not being sent.

Solutions:

1. Ensure the frontend Axios instance includes withCredentials: true so cookies are sent cross-origin
2. Verify the Axios request interceptor reads the CSRF cookie and attaches it as the X-CSRF-Token header
3. Check that CORS_ALLOW_CREDENTIALS=true in the backend .env
4. Check that the frontend origin is listed in CORS_ALLOWED_ORIGINS
5. Clear cookies and log in again to get a fresh CSRF token

Session Expired (4h Default, 12h Max)

Symptoms: API returns 401 Unauthorized after a period of inactivity.

Cause: Sessions have a default idle timeout of 4 hours, set by SESSION_TTL in .env. It is lowered by the System Settings Session Timeout and, further, by the acting role's Idle timeout on Administration > Roles: GET /auth/me returns the value in force as session_timeout_minutes. There is no JWT and no JWT_ACCESS_TOKEN_LIFETIME setting — if you find one in an old .env, it does nothing.

With SESSION_SLIDING_EXPIRATION enabled the TTL is extended on each request, but an absolute 12-hour cap is compiled in and is not configurable, so a session ends after 12 hours regardless of activity.

Solutions:

1. For development convenience, increase SESSION_TTL in .env (e.g. 12h) — values above 12 hours have no effect because of the absolute cap
2. The frontend should detect 401 responses and redirect to the login page
3. There is no refresh endpoint and no refresh token; a session is renewed by the sliding window or not at all

CORS Configuration for Cookie-Based Auth

Symptoms: Browser console shows CORS errors like Access-Control-Allow-Origin missing, or cookies are not being sent/received.

Cause: Cookie-based authentication requires specific CORS configuration. Browsers enforce stricter rules when credentials (cookies) are involved.

Solutions:

1. In the backend .env, set:

   CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
   CORS_ALLOW_CREDENTIALS=true

2. The Access-Control-Allow-Origin header cannot be * when credentials are used -- it must be the exact origin
3. Ensure the frontend uses withCredentials: true on all Axios requests
4. If testing from a different port or hostname, add it to CORS_ALLOWED_ORIGINS
5. When deploying behind a reverse proxy (Caddy, Nginx), ensure the proxy passes the Origin header through

lib/pq Connection String Format

Symptoms: Backend fails to start with pq: ... errors, or connection refused, password authentication failed, or database "sis" does not exist.

Cause: The Go backend uses lib/pq for PostgreSQL connections. The connection parameters are built from individual .env variables, not a single connection string.

Solutions:

1. Verify all database variables in .env:

   DB_HOST=127.0.0.1
   DB_PORT=5432
   DB_USER=postgres
   DB_PASSWORD=postgres
   DB_NAME=sis
   DB_SSLMODE=disable

2. Ensure PostgreSQL is running and accepting connections on the configured host/port
3. Verify the database exists: psql -h 127.0.0.1 -U postgres -c "SELECT 1" sis
4. If using DB_SSLMODE=disable locally, ensure your PostgreSQL instance does not require SSL
5. The lib/pq driver constructs a DSN like: host=127.0.0.1 port=5432 user=postgres password=postgres dbname=sis sslmode=disable
6. For DB_MAX_CONNS, the default is 25. Reduce if running multiple services on a small dev machine

Hot Reload Not Working (Air)

Symptoms: Code changes are not reflected without manual restart.

Solutions:

1. Ensure Air is installed: go install github.com/air-verse/air@latest
2. Run air from the sis_backendgo/ directory (not from the project root)
3. Check .air.toml for excluded paths that might be blocking detection
4. On Windows, file watchers can be unreliable with some editors -- try saving the file again

Frontend Dev Server Proxy Issues

Symptoms: API calls from the frontend return 404 or connection errors in development.

Solutions:

1. Ensure the Go backend is running on port 8000
2. Check that the Vite proxy configuration in vite.config.ts points to http://localhost:8000
3. Verify the Axios base URL in src/api/index.ts matches the expected API path

---

Getting Help

If issues persist:

1. Students: Contact Registrar or IT Help Desk
2. Faculty: Contact IT Help Desk
3. Administrators: Contact System Administrator

Provide:

• Description of the issue
• Steps to reproduce
• Error messages (screenshot if possible)
• Browser and device information