Skip to main content

Troubleshooting

General​

Common Issues​

Application won't start:

  • Ensure you meet the minimum system requirements
  • Try running as administrator (Windows) or with sudo (Linux)
  • Check that your antivirus isn't blocking the application

Can't connect to APIs:

  • Verify your internet connection
  • Check if the API endpoint is accessible from your network
  • Ensure firewall isn't blocking outbound connections

Map not loading:

  • Check your internet connection for basemap tiles
  • Verify the spatial data format is supported
  • Try refreshing the map view

Response is Invalid:

  • Check that you are using the right service type ie. don't try to use map service type for and expected json reponse
  • Ensure that the endpoint you are trying to test is actually able to return the expected response.

Installation​

Common Issues​

Permission denied errors:

  • Ensure you have administrator/sudo privileges
  • Check file permissions on the installer

Missing dependencies on Linux:

  • Install the required system libraries listed above
  • Try the AppImage version for better compatibility

macOS won't open (security warning):

  • Follow the macOS security steps above
  • Ensure you downloaded from the official source

Windows antivirus blocking:

  • Add Quetzly to antivirus whitelist
  • Temporarily disable real-time protection during installation

Getting Help​

If you encounter installation issues:

  1. Check the troubleshooting steps above
  2. Visit our Getting Started guide
  3. Report issues on our GitHub repository

Monitoring Issues​

Common Problems​

Endpoints not being checked:

  1. Verify the URL is correct and accessible
  2. Check that monitoring interval is saved
  3. Confirm the application is running continuously
  4. Review any error messages in the interface

False positive alerts:

  1. Test manually: Use the API section to test the endpoint
  2. Check network: Verify your internet connection
  3. Review timing: Consider if interval is too aggressive
  4. Examine responses: Look for intermittent issues

Missing monitoring data:

  1. Check that monitoring has been running continuously
  2. Verify the application hasn't been closed
  3. Review system resources (CPU, memory, network)
  4. Restart remove and add API again

Requests​

Request timeout:

  • Check network connection
  • Verify endpoint URL is correct
  • Try reducing request complexity

Authentication errors:

  • Verify credentials are correct
  • Check header format
  • Confirm authentication method

Invalid response format:

  • Check Accept headers
  • Verify service supports requested format
  • Review service documentation

Spatial data not displaying:

  • Verify coordinate reference system
    • The Viewer will automatically visualize data as web mercator. It's best to set your spatial reference output parameter to 4326 or 3857 in your request.
  • Check data extent and bounds
  • Ensure geometry is valid

Sets​

Common Import Issues​

File format errors:

  • Check file extension: Must be .json
  • Validate JSON: Use a JSON validator if import fails
  • Check encoding: Ensure UTF-8 encoding
  • File corruption: Try re-exporting the original set

Missing configurations:

  • Incomplete exports: Ensure all necessary data was saved
  • Version compatibility: Verify set was created with compatible Quetzly version
  • Custom settings: Some advanced settings may not transfer

Authentication issues:

  • Missing credentials: Authentication info may need manual entry
  • Token expiration: Refresh any time-sensitive authentication
  • Environment differences: Adjust URLs for different environments