🔧 Troubleshooting Guide

Q2G Issues

Cannot Connect to GeoServer

Causes:

• GeoServer is not running
• Incorrect GeoServer URL
• Network connectivity issues
• Firewall blocking connection

Solutions:

1. Verify GeoServer is running:

   http://localhost:8080/geoserver/web/

2. Check the GeoServer URL in Q2G
3. Verify network connectivity to the server
4. Check firewall rules allow port 8080
5. Try using the IP address instead of hostname

Authentication Failed

Causes:

• Incorrect username or password
• User doesn't have admin privileges
• User account is disabled

Solutions:

1. Verify username and password are correct
2. Check if the user has admin role in GeoServer
3. Try logging in to GeoServer web interface directly
4. Reset the password if needed
5. Check if the user account is active

Connection Timeout

Causes:

• GeoServer is slow to respond
• Network latency is high
• GeoServer is overloaded

Solutions:

1. Check your internet connection speed
2. Try again later if GeoServer is busy
3. Check GeoServer logs for errors
4. Increase timeout values if possible
5. Try uploading smaller files

Upload Issues

Layer Already Exists

Causes:

• Layer with same name already on GeoServer
• Auto-Overwrite option is disabled

Solutions:

1. Enable "Auto-Overwrite" option to replace existing layer
2. Rename the layer in QGIS
3. Delete the existing layer on GeoServer first
4. Use a different workspace

Invalid CRS

Causes:

• Layer doesn't have a CRS defined
• CRS is invalid or corrupted

Solutions:

1. Right-click layer in QGIS → Set Layer CRS
2. Choose the correct CRS for your data
3. Verify the CRS is valid
4. Try re-projecting the layer

File Too Large

Causes:

• File exceeds GeoServer upload limit
• Not enough disk space on GeoServer

Solutions:

1. Split large files into smaller chunks
2. Compress the file (use GeoPackage instead of Shapefile)
3. Increase GeoServer upload limit
4. Free up disk space on GeoServer
5. Upload to a different GeoServer instance

Invalid Geometry

Causes:

• Layer contains invalid geometries
• Self-intersecting polygons
• Duplicate vertices

Solutions:

1. Use Vector → Geometry Tools → Fix Geometries
2. Check for topology errors
3. Remove invalid features
4. Re-export the layer

Style Issues

Style Not Applied

Causes:

• Style upload failed
• Style not associated with layer
• Style name mismatch

Solutions:

1. Check upload log for style errors
2. Try uploading the style again
3. Verify the style exists on GeoServer
4. Check if the style is associated with the layer
5. Manually associate the style in GeoServer

Style Looks Different

Causes:

• QGIS style features not supported in SLD
• Color space differences
• Font availability differences

Solutions:

1. Simplify the QGIS style
2. Use standard fonts available on GeoServer
3. Test the style in a web browser
4. Manually edit the SLD on GeoServer
5. Use basic colors and symbols

SLD Export Error

Causes:

• Complex layer style
• Missing layer properties
• Unsupported style features

Solutions:

1. Simplify the layer style
2. Remove complex effects
3. Check layer CRS and geometry
4. Try with a basic single-symbol style

Workspace Issues

Cannot Create Workspace

Causes:

• Workspace name already exists
• Invalid workspace name
• Permission denied

Solutions:

1. Use a unique workspace name
2. Use only alphanumeric characters and underscores
3. Verify you have admin permissions
4. Check GeoServer logs for errors

Workspace Not Appearing

Causes:

• Workspace list not refreshed
• Workspace creation failed silently

Solutions:

1. Click "Refresh" button to reload workspace list
2. Check GeoServer web interface for workspace
3. Try creating the workspace again

PostGIS Issues

PostGIS Connection Failed

Causes:

• Database server not running
• Incorrect connection parameters
• Database doesn't exist
• User doesn't have permissions

Solutions:

1. Verify PostgreSQL is running
2. Check connection parameters (host, port, database, user)
3. Verify database exists
4. Check user has SELECT permissions
5. Test connection using psql command line

PostGIS Layer Not Found

Causes:

• Table doesn't exist in database
• Table name is incorrect
• User doesn't have access to table

Solutions:

1. Verify table exists in database
2. Check table name spelling
3. Verify user has SELECT permissions on table
4. Check if table has geometry column

Performance Issues

Slow Upload Speed

Causes:

• Large file size
• Slow network connection
• GeoServer is busy

Solutions:

1. Split large files into smaller chunks
2. Check internet connection speed
3. Upload during off-peak hours
4. Reduce file size by filtering data

Plugin Freezes

Causes:

• Large file processing
• Network timeout
• Memory issues

Solutions:

1. Wait for operation to complete
2. Close other applications to free memory
3. Restart QGIS if it remains frozen
4. Try uploading smaller files

Getting Help

Checking Logs

When troubleshooting, check the upload log:

• Look for error messages (red text)
• Check for warning messages (orange text)
• Review debug messages (blue text)
• Copy the log for reference

GeoServer Logs

For server-side errors, check GeoServer logs:

1. Go to GeoServer web interface
2. Navigate to About → Logs
3. Look for error messages
4. Check timestamps match your upload time

QGIS Logs

For QGIS-related errors:

1. Go to Help → Log Messages
2. Look for Q2G messages
3. Check for Python errors

Common Error Messages

Next Steps

• Configuration - Verify your settings
• Layer Upload - Try uploading again
• FAQ - Check frequently asked questions