coollabsio/coolify · error · RuntimeException

Invalid {$fieldName}: contains forbidden characters.

Error message

Invalid {$fieldName}: contains forbidden characters.

What it means

ApplicationDeploymentJob::validatePathField() rejects values that do not match ValidationPatterns::FILE_PATH_PATTERN (/^\/[a-zA-Z0-9._\-\/~@+]+$/): the path must be absolute (start with /) and contain only alphanumerics, dots, hyphens, underscores, slashes, ~, @, +. It guards path fields (e.g. dockerfile/compose locations read during deployment) before they reach the filesystem or shell commands.

Source

Thrown at app/Jobs/ApplicationDeploymentJob.php:4676

            }
        }

        $composeFile['services'] = $services;
        $existingSecrets = data_get($composeFile, 'secrets', []);
        if ($existingSecrets instanceof Collection) {
            $existingSecrets = $existingSecrets->toArray();
        }
        $composeFile['secrets'] = array_replace($existingSecrets, $secrets);

        $this->application_deployment_queue->addLogEntry('Added build secrets configuration to docker-compose file (using environment variables).');

        return $composeFile;
    }

    private function validatePathField(string $value, string $fieldName): string
    {
        if (! preg_match(ValidationPatterns::FILE_PATH_PATTERN, $value)) {
            throw new \RuntimeException("Invalid {$fieldName}: contains forbidden characters.");
        }
        if (str_contains($value, '..')) {
            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

View on GitHub (pinned to 70b9acc424)

Solutions

1. Make the value an absolute path starting with '/', e.g. '/docker/Dockerfile' or '/app/compose.yaml'.
2. Remove spaces, quotes, $, backslashes, and other characters outside [A-Za-z0-9._-/~@+].
3. If you control the form/API, validate with ValidationPatterns::filePathRules() at save time.

Example fix

# before: relative path with a space
dockerfileLocation: 'my app/Dockerfile'

# after: absolute path, allowed characters only
dockerfileLocation: '/my-app/Dockerfile'

// Reject bad path values at input time
$validated = $request->validate(
    ValidationPatterns::filePathRules()
    + ValidationPatterns::filePathMessages()
);

function isValidFilePath(?string $value): bool
{
    return blank($value) || preg_match(\App\Support\ValidationPatterns::FILE_PATH_PATTERN, $value) === 1;
}

When it happens

Trigger: A path field consumed during deployment contains a relative path ('Dockerfile', 'src/..'), spaces, quotes, $, parentheses, or non-ASCII characters; any value not beginning with '/'.

Common situations: Users entering './docker' or 'docker/Dockerfile' instead of '/data/coolify/app/docker/Dockerfile'; Windows-style backslash paths; paths with spaces pasted from a terminal.

Understand the failure class

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

Related errors

• Invalid dockerfile_target_build: contains forbidden characte
• Invalid {$fieldName}: path traversal detected.
• Invalid {$fieldName}: contains forbidden shell characters.
• Invalid container name: contains forbidden characters.
• Pre-deployment command: Could not find a valid container. Is

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