What causes "Invalid container name: contains forbidden characters." in coollabsio/coolify?

Use a name like 'my-app-1': starts with a letter/digit, then only [a-zA-Z0-9._-].

coollabsio/coolify · error · RuntimeException

Invalid container name: contains forbidden characters.

Error message

Invalid container name: contains forbidden characters.

What it means

validateContainerName() checks the value against ValidationPatterns::CONTAINER_NAME_PATTERN (/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/), mirroring Docker's own container naming rules: must start with a letter or digit, then letters, digits, dots, hyphens, underscores. The check runs when a deployment needs to resolve which container to execute commands in; values with spaces, leading -/._, $, or other characters throw.

Source

Thrown at app/Jobs/ApplicationDeploymentJob.php:4697

            throw new \RuntimeException("Invalid {$fieldName}: path traversal detected.");
        }

        return $value;
    }

    private function validateShellSafeCommand(string $value, string $fieldName): string
    {
        if (! preg_match(ValidationPatterns::SHELL_SAFE_COMMAND_PATTERN, $value)) {
            throw new \RuntimeException("Invalid {$fieldName}: contains forbidden shell characters.");
        }

        return $value;
    }

    private function validateContainerName(string $value): string
    {
        if (! preg_match(ValidationPatterns::CONTAINER_NAME_PATTERN, $value)) {
            throw new \RuntimeException('Invalid container name: contains forbidden characters.');
        }

        return $value;
    }

    /**
     * Resolve which container to execute a deployment command in.
     *
     * For single-container apps, returns the sole container.
     * For multi-container apps, matches by the user-specified container name.
     * If no container name is specified for multi-container apps, logs available containers and returns null.
     */
    private function resolveCommandContainer(Collection $containers, ?string $specifiedContainerName, string $commandType): ?array
    {
        if ($containers->count() === 0) {
            return null;
        }

View on GitHub (pinned to 70b9acc424)

Solutions

Use a name like 'my-app-1': starts with a letter/digit, then only [a-zA-Z0-9._-].
Trim whitespace and remove quotes/backslashes introduced by copy-paste.
If you store the value via API/UI, validate with ValidationPatterns::containerNameRules() at input time.

Example fix

# before: leading underscore and space
dockerRunCommandTag/container: '_my app'

# after: pattern-compliant name
container: 'my-app'

Defensive patterns

Strategy: validation

Validate before calling

$validated = $request->validate(
    ['container_name' => ValidationPatterns::containerNameRules()]
    + ['container_name.regex' => 'Container name must start with a letter or digit and contain only letters, digits, dots, hyphens, underscores.']
);

Type guard

function isValidContainerName(string $name): bool
{
    return preg_match(\App\Support\ValidationPatterns::CONTAINER_NAME_PATTERN, trim($name)) === 1;
}

Prevention

Trim whitespace on save; copy-paste often adds stray characters.
Avoid leading underscores/hyphens even though Docker tolerates them — this pattern does not.
Derive container names programmatically from validated service names instead of free-text input.

When it happens

Trigger: A user-specified container name field (used to pick a container in multi-container apps) contains e.g. 'my app', '-app', '_app', 'app$1', or trailing whitespace; copy-paste introduced invisible characters or quotes.

Common situations: Container names copied from docker ps with extra columns; names derived from service names containing forbidden characters; manually typed names starting with underscore (Docker allows it, this stricter pattern does not).

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of coollabsio/coolify@70b9acc424 (2026-08-17). Data as JSON: /api/errors/a33fc8ea1d40f1f1. Report an issue: GitHub.