Skip to content

Troubleshooting Guide

Document Version: 1.5 | Last Updated: March 2026

What's New in v1.3 (February 2026): - Updated connection troubleshooting for single-owner communications model - Automatic reconnection behavior documentation

Solutions for common problems with the Science Scheduler system.

Plugin Issues

Plugin Not Loading in NINA

Symptoms: - Plugin doesn't appear in NINA's plugin list - Plugin appears but shows error status

Solutions:

  1. Check NINA version
  2. Required: NINA 3.0.0.2001 or later

  3. Update NINA if needed

  4. Verify .NET Runtime

  5. Required: .NET 8.0 Runtime

  6. Download from: https://dotnet.microsoft.com/download/dotnet/8.0

  7. Check file location

  8. Files must be in: %LOCALAPPDATA%\NINA\Plugins\ScienceScheduler\

  9. Not in a subfolder within that directory

  10. Check for missing files

  11. NINA.Plugin.ScienceScheduler.dll is required

  12. manifest.json is required

  13. Restart NINA

  14. Close NINA completely (check Task Manager)
  15. Reopen NINA

Can't Connect to Server

Symptoms: - Status shows "Disconnected" or "Connecting..." - Connection timeout errors

Solutions:

  1. Verify Server URL
  2. Check the URL format: ws://hostname:port or wss://hostname:port

  3. Confirm URL with your administrator

  4. Check network connectivity

  5. Can you ping the server hostname?

  6. Is the port open? (default: 8080)

  7. Firewall settings

  8. Windows Firewall may block WebSocket connections

  9. Add exception for NINA or the specific port

  10. VPN/Proxy issues

  11. Some VPNs block WebSocket traffic

  12. Try disconnecting VPN temporarily

  13. Server status

  14. Confirm with administrator that server is running
  15. Check if other observatories are connecting

Note: The plugin uses automatic reconnection with exponential backoff. If the connection drops, it will retry automatically (starting at 1 second, up to 60 seconds between attempts). You should see "Reconnecting..." status during this process. If it never reconnects, check the above items.

Configuration Required Error

Symptoms: - Plugin shows "Configuration Required" status - Cannot enable plugin

Solutions:

Check all required fields in plugin settings:

Field Requirement
Server URL Must be valid WebSocket URL
Observatory ID/Code 3-20 chars, alphanumeric/dash/underscore
Observatory Name Cannot be blank
Contact Email Must be valid email format

Authentication Failed

Symptoms: - "Authentication failed" error - "Invalid API key" message

Solutions:

  1. Check API key
  2. Copy/paste carefully (no extra spaces)

  3. Key may have expired - contact administrator

  4. For new registrations

  5. Leave API key blank
  6. Fill in all required observatory information

  7. Wait for administrator approval

  8. Fingerprint mismatch

  9. Hardware changed since registration?
  10. Contact a server administrator to reset your fingerprint

Registration Issues

Registration Not Completing

Symptoms: - Plugin connects but stays "pending" - No API key received

Solutions:

  1. Contact administrator
  2. Registrations require manual approval

  3. Provide your Observatory ID and contact email

  4. Check required fields

  5. All required fields must be valid

  6. Email must be proper format

  7. Check server logs (administrators)

  8. Look for registration errors
  9. Verify fingerprint is being received

Fingerprint Mismatch

Symptoms: - "Fingerprint mismatch" error - Previously working connection now fails

Causes: - Hardware was replaced - Virtual machine was recreated - Windows reinstallation

Solutions:

  1. Contact a server administrator to:
  2. Reset your hardware fingerprint (only server admins can do this)

  3. The plugin will auto-enroll the new fingerprint on next connection

  4. Or re-register

  5. Use new observatory code
  6. Complete registration process again

Observation Issues

No Observations Being Assigned

Symptoms: - Plugin connected and ready - No observations received

Check:

  1. Operations enabled?

  2. "Enable Operations" must be ON in plugin settings

  3. Queue has work?

  4. Check with administrator if queue has pending observations

  5. Observations may all be for different time windows

  6. Visibility constraints

  7. Targets must be visible from your location

  8. Check altitude and other constraints

  9. Equipment capabilities

  10. Your observatory must have required equipment
  11. Some observations need specific filters

Observation Stuck in Status

Symptoms: - Observation shows "assigned" or "in_progress" but not running - Status never changes

Solutions:

  1. Check NINA sequence
  2. Is the Science Scheduler container running?

  3. Are there errors in the NINA log?

  4. Clear local database

  5. Plugin Settings > Database Management > Clear Local Database

  6. Removes stuck state data

  7. Restart sequence

  8. Stop and restart the NINA sequence

  9. Plugin will reconnect and sync state

  10. Understand the monitors

  11. The server has automated monitors that detect stuck observations (24h for in_progress, 48h for assigned)
  12. See Observation Lifecycle for details on all statuses, transitions, and monitors

FITS Files Not Uploading

Symptoms: - Observations complete but files don't appear on server - Upload errors in logs

Solutions:

  1. Check upload queue
  2. Files are queued locally before upload

  3. Network issues may delay uploads

  4. Verify network connection

  5. Server must be reachable

  6. Check for firewall blocking uploads

  7. Clear upload queue if stuck

  8. Use "Clear Local Database" in plugin settings

  9. Note: This clears pending uploads

  10. Check disk space

  11. Both local and server storage
  12. Full storage can prevent uploads

Why Isn't My Observation Running?

If your observation is stuck in "Pending" or "Assigned" and never starts, it's usually because one or more scheduling constraints aren't being met.

Constraints Checked by the Scheduler

The scheduler evaluates these constraints before dispatching an observation:

Constraint What It Checks
Altitude Target must be above the minimum altitude setting
Airmass Target's airmass must be below the maximum airmass setting
Moon Separation Target must be at least the configured degrees away from the moon
Twilight Sky must be dark enough (astronomical, nautical, or civil twilight)
Weather Safety Observatory safety device must report "safe" conditions

If any constraint is violated, the observation cannot start.

Viewing Constraint Violations

The observation detail page shows which constraints are currently preventing execution. Look for the Constraint Violations section, which lists each violated constraint with its current value vs. the required value.

Common Violations and Fixes

Target altitude too low:

  • The target hasn't risen high enough yet, or has already set too low
  • Fix: Wait for the target to reach higher altitude, or lower the minimum altitude constraint (with the understanding that lower altitude means more atmospheric distortion)

Moon too close:

  • The target is within the configured moon separation distance
  • Fix: Reduce the moon separation constraint if the observation can tolerate more moonlight, or wait for the moon to move. The moon moves ~13° per day

Airmass too high:

  • The target is too close to the horizon, resulting in excessive atmospheric path length
  • Fix: Increase the maximum airmass constraint (e.g., from 1.5 to 2.0), or wait for the target to transit higher

Weather unsafe:

  • The observatory safety device is reporting unsafe conditions
  • Fix: Wait for conditions to improve. Weather holds are automatic — the scheduler will dispatch the observation once safety clears

Twilight too bright:

  • The sky is not dark enough for the configured twilight requirement
  • Fix: Wait for deeper darkness, or change the twilight constraint if your observation can tolerate brighter sky

Partial Completion

Sometimes an observation starts but stops partway through because conditions change (e.g., target sets below minimum altitude, weather turns unsafe). The scheduler tracks this as a partial completion when at least 10% of exposures were captured.

Partially completed observations show what percentage was achieved and why execution stopped. You can resubmit the observation to capture the remaining exposures.

Autofocus Problems

For autofocus-specific troubleshooting (unexpected AF behavior, triggers not firing, initial AF failures, missing log entries), see the dedicated Autofocus Guide — Troubleshooting section.

Web Interface Issues

Can't Log In

Symptoms: - Login fails with valid credentials - "Invalid credentials" error

Solutions:

  1. Check credentials
  2. Email/password correct?

  3. Caps Lock on?

  4. Account status

  5. Account may be disabled

  6. Contact administrator

  7. Browser issues

  8. Clear cookies and cache
  9. Try different browser

Observations Not Updating

Symptoms: - Status changes not reflected in UI - Need to refresh to see updates

Solutions:

  1. Check WebSocket connection
  2. Browser console may show connection errors

  3. Try refreshing the page

  4. Browser compatibility

  5. Use modern browser (Chrome, Firefox, Edge)
  6. Disable ad blockers that may interfere

Page Errors or Blank Screens

Symptoms: - Pages don't load properly - JavaScript errors

Solutions:

  1. Hard refresh
  2. Ctrl+Shift+R (Windows)

  3. Cmd+Shift+R (Mac)

  4. Clear browser cache

  5. Settings > Clear browsing data

  6. Check network tab

  7. Open browser dev tools (F12)
  8. Look for failed requests

Weather and Safety Issues

Observatory Marked Unsafe

Symptoms: - Observatory not receiving observations - Safety status shows "unsafe" in admin interface

Solutions:

  1. Check safety device
  2. Verify your weather/safety device is connected and reporting

  3. Check NINA's safety monitor shows correct status

  4. Review safety events

  5. Check observatory history for safety event timestamps

  6. Compare with actual weather conditions

  7. Manual override (administrators only)

  8. If the safety device is reporting incorrectly, contact your administrator
  9. Administrators can review safety events in the observatory history

Equipment Configuration Changed Events

Symptoms: - Observatory history shows "equipment_configuration_changed" events - May indicate unexpected equipment changes

Causes: - Changed camera, mount, or filter wheel in NINA - Reconnected with different equipment profile - Updated NINA equipment settings

Solution: These events are informational. Review the history to confirm the change was intentional. If unexpected, check your NINA equipment profile.

Notification Issues

Not Receiving Email Notifications

Symptoms: - Observation changed state but no email received

Solutions:

  1. Check email is verified — unverified emails cannot receive notifications
  2. Check spam/junk folder — notification emails may be filtered
  3. Verify email notifications are enabled in your Profile → Notification Preferences
  4. Check per-observation settings — ensure email is checked and the relevant state is selected for the observation
  5. Use Test Notifications in your profile to verify email delivery works

Not Receiving Pushover Notifications

Symptoms: - Observation changed state but no Pushover notification received

Solutions:

  1. Verify Pushover User Key is correct in Profile → Notification Preferences
  2. Check device names — if specified, ensure they match your Pushover device names exactly
  3. Verify Pushover app is installed and configured on your device
  4. Use Test Notifications in your profile to verify Pushover delivery
  5. Contact administrator — the server may not have Pushover configured (PUSHOVER_APP_TOKEN)

Notification Section Not Showing on Observation Form

Symptoms: - No notification options visible when creating an observation

Solution:

  • You must enable at least one notification channel (Email or Pushover) in your Profile → Notification Preferences first
  • The notification section only appears when you have at least one channel enabled

Advanced Troubleshooting

Database Integrity (Administrators)

For data issues (orphaned references, stuck statuses, missing files), administrators can run integrity scans to detect and repair problems. See the System Administration guide for full details.

AI Log Analysis (Administrators)

For complex issues, administrators can use AI-powered log analysis. The system automatically collects NINA plugin logs and can submit them to Claude for comprehensive diagnostic reports. See the Log Analysis Guide for full details.

Using Docker Log Search (Administrators)

For server-side issues, administrators can use the built-in log viewer:

  1. Navigate to System → Log Viewer in the admin interface
  2. Select the relevant container (e.g., nina-scheduler-api)
  3. Use regex search to find specific error patterns
  4. Common search patterns:
  5. error|Error|ERROR - Find all errors
  6. observatory_id.*YOUR_CODE - Find events for a specific observatory
  7. WebSocket.*close - Find connection closures

Getting Help

Contact Support

Use the Contact Support page in the web interface to submit a support request.

How to submit a request:

  1. Navigate to Contact Support from the main menu
  2. Select a category:
  3. Bug Report — something isn't working as expected
  4. Feature Request — suggest a new feature or improvement
  5. Account Issue — login problems, permissions, profile issues
  6. Observation Issue — problems with a specific observation
  7. General Question — usage questions, how-to inquiries
  8. Other — anything that doesn't fit the above categories
  9. Enter a subject (5–200 characters) summarizing your issue
  10. Provide a detailed description (20–5,000 characters) with as much context as possible
  11. Your email is auto-populated from your account
  12. Click Submit

You'll receive a confirmation with a ticket number in the format SUP-YYYY-NNNNN (e.g., SUP-2026-00042). Expected response time is 24–48 hours.

Viewing past requests:

Navigate to Contact Support and click My Requests to see your submission history, including current status and any responses.

Before Contacting Support

Gather this information:

For plugin issues: - NINA version - Plugin version (from plugin list) - Windows version - Error messages (exact text) - NINA log file (relevant sections)

For web interface issues: - Browser and version - Error messages - Screenshots of the problem

For observation issues: - Observation ID - Observatory code - Time when issue occurred - Status that was displayed

Log Locations

NINA logs: 

%LOCALAPPDATA%\NINA\Logs\

Plugin state database: 

%LOCALAPPDATA%\NINA\ScienceScheduler\

Contact Information

  • Technical issues: Contact your system administrator
  • Account issues: Contact your institution's scheduler admin
  • Bug reports: Submit a bug report
  • Feature requests: Request a feature
  • NINA and advanced sequencing: Join the NINA Discord for community help with NINA features and building advanced sequences

Quick Reference

Problem First Thing to Try
Plugin won't load Check NINA version, .NET 8.0
Can't connect Verify server URL and network
Auth failed Check API key or re-register
No observations Check "Enable Operations" is ON
Stuck observation Clear local database
Upload failing Check network, clear queue
Can't log in Clear browser cache
Observation won't start Check constraint violations on detail page
Safety/weather issue Check safety device, review history
Equipment changed Review observatory history events
No notification emails Check profile preferences, verify email
No Pushover alerts Check user key, test from profile