Troubleshooting#

Common issues and solutions for GeoServer CLI.

Connection Issues#

Cannot Connect to GeoServer#

Symptom: connection refused or timeout errors

Solutions:

  1. Verify GeoServer is running:

    1

    curl http://localhost:8080/geoserver/rest/about/version.json

  2. Check base URL:

    1
2
3

    # Must include /rest at the end
./geoserver-cli config show
# base_url should be: http://localhost:8080/geoserver/rest

  3. Verify credentials:

    1
2

    # Test with curl
curl -u admin:geoserver http://localhost:8080/geoserver/rest/workspaces.json

  4. Check firewall/network:

    • Ensure port 8080 is open
    • Check if VPN or proxy is interfering
    • Try accessing GeoServer web UI

Authentication Failed#

Symptom: 401 Unauthorized errors

Solutions:

  1. Verify credentials:

    1
2

    # Check what's being used
./geoserver-cli config show

  2. Reset admin password in GeoServer:

    • Access GeoServer web UI
    • Security → Users → admin

  3. Check for special characters:

    1
2

    # Passwords with special characters need quotes
password = "p@ssw0rd!"

SSL/TLS Errors#

Symptom: certificate verify failed or SSL errors

Solutions:

  1. For self-signed certificates (dev only):

    1
2

    # Skip TLS verification (NOT for production)
export GODEBUG=http2debug=2

  2. Use HTTP instead of HTTPS (dev only):

    1

    base_url = "http://localhost:8080/geoserver/rest"

Configuration Issues#

Config File Not Found#

Symptom: config file not found errors

Solutions:

  1. Initialize config:

    1

    ./geoserver-cli config init

  2. Check config path:

    1
2
3
4
5

    # Should output: .githooks (or empty)
git config --get core.hooksPath

# Set if needed
export GEOSRVCLI_CONFIG=default

  3. Verify file exists:

    1

    ls -la configs/default.config.toml

Environment Variables Not Working#

Symptom: Config values not being applied

Solutions:

  1. Check precedence:

    1
2
3
4
5

    # CLI flags override everything
./geoserver-cli workspace list --base-url http://example.com/geoserver/rest

# Environment variables override config file
export GEOSRVCLI_ENDPOINT=http://example.com/geoserver/rest

  2. Verify environment variables:

    1

    env | grep GEOSRVCLI

  3. Check spelling:

    • Must be GEOSRVCLI_ prefix (not GEOSERVER_)
    • Use GEOSRVCLI_ENDPOINT (not GEOSRVCLI_BASE_URL)

Publishing Issues#

PostGIS Connection Failed#

Symptom: Cannot publish layers from PostGIS

Solutions:

  1. Test PostGIS connection:

    1

    psql -h localhost -U postgres -d gis -c "SELECT PostGIS_version();"

  2. Check PostGIS config:

    1
2

    ./geoserver-cli config show
# Verify postgis section

  3. Test with publish dry-run:

    1

    ./geoserver-cli publish postgis --all -w test --dry-run

No Spatial Tables Found#

Symptom: no publishable layers selected

Solutions:

  1. Verify spatial tables exist:

    1
2
3

    SELECT f_table_name, f_geometry_column, srid, type
FROM geometry_columns
WHERE f_table_schema = 'public';

  2. Check schema:

    1
2

    # Specify correct schema
./geoserver-cli publish postgis --all -w test --pg-schema public

File Import Failed#

Symptom: Importer extension errors

Solutions:

  1. Verify Importer extension is installed:

    • Check GeoServer web UI → About → Extensions
    • Should see “Importer Extension”

  2. Install if missing:

    • Download from GeoServer downloads
    • Copy JAR to webapps/geoserver/WEB-INF/lib/
    • Restart GeoServer

  3. Check file format:

    1
2
3
4
5

    # Shapefile must be zipped
zip -r data.zip data.shp data.shx data.dbf data.prj

# GeoTIFF should work directly
./geoserver-cli publish file --file data.tif -w test

Layer Issues#

Layer Not Visible in QGIS#

Symptom: Layer exists but doesn’t show in QGIS

Solutions:

  1. Check layer is advertised:

    1

    ./geoserver-cli layer update my_layer --advertised true

  2. Verify layer is enabled:

    1

    ./geoserver-cli layer update my_layer --enabled true

  3. Check QGIS auth configuration:

Style Not Applied#

Symptom: Layer uses default style instead of custom

Solutions:

  1. Set default style:

    1

    ./geoserver-cli layer update my_layer --default-style my_style

  2. Verify style exists:

    1

    ./geoserver-cli style list | grep my_style

Performance Issues#

Slow Commands#

Symptom: Commands take too long

Solutions:

  1. Increase timeout:

    1

    ./geoserver-cli workspace list --timeout 60s

  2. Check GeoServer performance:

    • GeoServer web UI → Server Status
    • Check memory usage

  3. Use concurrency for bulk operations:

    1
2

    # Adjust based on your system
./geoserver-cli publish postgis --all -w test --concurrency 4

Memory Issues#

Symptom: Out of memory errors

Solutions:

  1. Process in batches:

    1
2

    # Instead of --all, use --layers with small batches
./geoserver-cli publish postgis --layers table1,table2,table3 -w test

  2. Increase GeoServer memory:

    1
2

    # In GeoServer startup script
JAVA_OPTS="-Xms512m -Xmx2048m"

Development Issues#

Pre-commit Hook Failing#

Symptom: Cannot commit due to hook errors

Solutions:

  1. Install required tools:

    1

    ./scripts/install-tools.sh

  2. Run checks manually:

    1
2
3
4

    gofmt -w .
go vet ./...
./bin/golangci-lint run ./...
go test ./...

  3. Bypass (emergency only):

    1

    git commit --no-verify -m "message"

Build Failures#

Symptom: go build fails

Solutions:

  1. Check Go version:

    1

    go version  # Should be 1.24 or later

  2. Update dependencies:

    1
2

    go mod download
go mod tidy

  3. Clean and rebuild:

    1
2
3

    go clean -cache
rm geoserver-cli
go build -o geoserver-cli ./cmd/geoserver-cli

Getting Help#

Check Logs#

Enable verbose output:

1
2
3
4
5

# Set Go's HTTP debug
export GODEBUG=http2debug=2

# Run command
./geoserver-cli workspace list

Report Issues#

If you can’t resolve the issue:

  1. Check existing issues: https://gitlab.com/aice/geoserver-cli/-/issues
  2. Create a new issue with:
    • CLI version: ./geoserver-cli version
    • Command that failed
    • Full error message
    • Configuration (redact passwords!)

Community Support#

  • GitLab Issues: Report bugs and feature requests
  • Discussions: Ask questions and share tips
  • Contributing Guide: Learn how to contribute fixes

Quick Diagnostics#

Run these commands to gather diagnostic information:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# CLI version
./geoserver-cli version

# Configuration
./geoserver-cli config show --redact

# GeoServer connection
curl -u admin:password http://localhost:8080/geoserver/rest/about/version.json

# Environment
env | grep GEOSRVCLI

# Git hooks status
git config --get core.hooksPath
Backward Quick Start Commands Forward