Error Handling#

Understanding and handling errors in GeoServer CLI.

Error Types#

API Errors#

Errors returned by GeoServer REST API.

Format:

1

GET http://localhost:8080/geoserver/rest/workspaces.json failed with HTTP 404: Not Found

Common HTTP Status Codes:

  • 404: Resource not found (workspace, datastore, layer, etc.)
  • 401: Authentication failed (invalid credentials)
  • 403: Forbidden (insufficient permissions)
  • 500: Internal server error (GeoServer issue)
  • 400: Bad request (invalid parameters)

Handling:

1
2
3
4
5

# Check if resource exists first
./geoserver-cli workspace get my_workspace || echo "Workspace not found"

# Verify credentials
./geoserver-cli workspace list || echo "Authentication failed"

Configuration Errors#

Errors related to configuration files or settings.

Examples:

1
2
3

Error: config file not found: configs/missing.config.toml
Error: missing required field: geoserver.base_url
Error: file permissions too permissive (0644), should be 0600

Handling:

1
2
3
4
5

# Validate configuration
./geoserver-cli config validate

# Show resolved configuration
./geoserver-cli config show

Connection Errors#

Network or connection issues.

Examples:

1
2

Error: perform request: dial tcp: connect: connection refused
Error: context deadline exceeded

Handling:

1
2
3
4
5

# Check GeoServer is accessible
curl http://localhost:8080/geoserver/rest/workspaces.json

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

Validation Errors#

Input validation failures.

Examples:

1
2
3

Error: expected workspace name, or use --default
Error: --params is required
Error: invalid boolean value "maybe"

Handling:

1
2
3
4
5

# Check command syntax
./geoserver-cli workspace get --help

# Verify required flags
./geoserver-cli store create my_store --params @conn.json

Exit Codes#

GeoServer CLI uses standard exit codes:

  • 0: Success
  • 1: General error
  • 2: Usage error (invalid arguments)

Error Messages#

Verbose Output#

Errors include context:

1
2
3

Error: create postgis datastore "postgis": 
  GET http://localhost:8080/geoserver/rest/workspaces/my_workspace/datastores/postgis.json 
  failed with HTTP 404: Not Found

Error Chains#

Errors preserve context through error wrapping:

1
2
3
4

Error: publish layer "roads": 
  create featuretype: 
  POST http://localhost:8080/geoserver/rest/workspaces/my_workspace/datastores/postgis/featuretypes 
  failed with HTTP 500: Internal Server Error

Common Issues#

Authentication Failed#

Symptom:

1

Error: GET ... failed with HTTP 401: Unauthorized

Solutions:

  1. Verify credentials in config or environment
  2. Check GeoServer user permissions
  3. Test with curl:
    1

    curl -u username:password http://localhost:8080/geoserver/rest/workspaces.json

Resource Not Found#

Symptom:

1

Error: GET ... failed with HTTP 404: Not Found

Solutions:

  1. Verify resource exists:
    1
2

    ./geoserver-cli workspace list
./geoserver-cli store list -w my_workspace
  2. Check workspace/datastore names (case-sensitive)
  3. Verify resource wasn’t deleted

Connection Timeout#

Symptom:

1

Error: context deadline exceeded

Solutions:

  1. Increase timeout:
    1

    ./geoserver-cli workspace list --timeout 120s
  2. Check network connectivity
  3. Verify GeoServer is running and accessible

Invalid JSON#

Symptom:

1

Error: decode json: invalid character 'x' looking for beginning of value

Solutions:

  1. Validate JSON syntax:
    1

    cat params.json | jq .
  2. Check file encoding (must be UTF-8)
  3. Verify JSON structure matches GeoServer requirements

Debugging#

Enable Verbose Output#

Some commands support verbose output (if implemented):

1
2
3
4
5

# Show resolved configuration
./geoserver-cli config show

# Dry run to preview actions
./geoserver-cli publish postgis --all -w my_workspace --dry-run

Test Connection#

1
2
3
4
5

# Simple connection test
./geoserver-cli workspace list

# Test with different config
./geoserver-cli workspace list --config dev

Check Configuration#

1
2
3
4
5

# Validate config file
./geoserver-cli config validate

# Show resolved settings
./geoserver-cli config show

Best Practices#

  1. Always validate configuration before operations
  2. Use dry-run for destructive or bulk operations
  3. Check error messages for specific HTTP status codes
  4. Verify prerequisites (workspace exists, datastore configured, etc.)
  5. Test connectivity before running commands
  6. Handle errors gracefully in scripts (check exit codes)

Script Error Handling#

Bash Example#

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

#!/bin/bash
set -e  # Exit on error

# Validate config first
if ! ./geoserver-cli config validate; then
  echo "Configuration invalid"
  exit 1
fi

# Run command with error handling
if ! ./geoserver-cli publish postgis --all -w production; then
  echo "Publishing failed"
  exit 1
fi

echo "Success"

Error Checking#

1
2
3
4
5
6
7
8

# Check exit code
./geoserver-cli workspace list
if [ $? -ne 0 ]; then
  echo "Command failed"
fi

# Or use && and ||
./geoserver-cli workspace list && echo "Success" || echo "Failed"
Backward Environment Variables Development Forward