Knowledge Base Troubleshooting Hub

Common Configuration Errors

Invalid YAML Syntax

▼

This error occurs when the configuration file contains malformed YAML.

Typical causes:

  • Incorrect indentation (mixing spaces and tabs)
  • Missing colons or quotes
  • Using reserved keywords as keys

Example of a broken snippet:

database:
  host: "localhost"
  port 5432   # missing colon
  user: admin
    password: secret  # extra indentation

Fix:

database:
  host: "localhost"
  port: 5432
  user: admin
  password: secret

Missing Environment Variables

▼

When the application expects certain environment variables that are not set, it fails to start.

Resolution steps:

  1. Check the required variables in the documentation.
  2. Verify they are exported in your shell or defined in the `.env` file.
  3. Restart the service after setting them.

Example `.env`:

APP_PORT=8080
DB_HOST=127.0.0.1
DB_USER=appuser
DB_PASS=securepassword

Port Conflict

▼

The configured listening port is already in use by another process.

How to diagnose:

# Linux/macOS
sudo lsof -iTCP -sTCP:LISTEN | grep 8080

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort 8080).OwningProcess

Solution:

  • Change the port in your configuration.
  • Stop the conflicting service.

Incorrect File Permissions

▼

The process does not have read/write access to a required file or directory.

Check permissions:

# Example for a config file
ls -l /etc/myapp/config.yaml

Typical fix:

sudo chown myapp:myapp /etc/myapp/config.yaml
sudo chmod 640 /etc/myapp/config.yaml

Unsupported Configuration Version

▼

Newer versions of the software may reject older configuration schema versions.

Action plan:

  1. Identify the `schema_version` field in your config.
  2. Update it to the version required by the current application release.
  3. Refer to the migration guide for any structural changes.

Example migration snippet:

# Old
schema_version: 1

# Updated
schema_version: 3
logging:
  level: "info"