## Q2G Issues

### Cannot Connect to GeoServer

Error: "Connection refused" or "Unable to connect"

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

Error: "Authentication failed" or "Unauthorized"

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

Error: "Connection timeout" or "Request timed out"

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

Error: "Layer already exists" or "Datastore 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

Error: "Invalid CRS" or "No CRS defined"

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

Error: "File too large" or "Upload failed"

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

Error: "Invalid geometry" or "Geometry error"

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

Error: "Style not applied" or "Default style shown"

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

Issue: "Style renders differently on GeoServer"

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

Error: "Failed to export SLD" or "SLD generation 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

Error: "Failed to 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

Issue: "Created workspace not showing in list"

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

Error: "Cannot connect to PostGIS" or "Database 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

Error: "PostGIS layer not found" or "Table doesn't exist"

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

Issue: "Upload is very slow"

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

Issue: "Q2G becomes unresponsive"

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

Error Message | Meaning | Solution
--- | --- | ---
Connection refused | Cannot reach GeoServer | Check GeoServer is running and URL is correct
Unauthorized | Authentication failed | Check username and password
Layer exists | Layer already on GeoServer | Enable Auto-Overwrite or rename layer
Invalid CRS | Layer has no CRS | Set layer CRS in QGIS
File not found | Source file missing | Check file path and permissions

## Next Steps

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

↑