symfony/translation · error · RuntimeException

Translation Writer was not able to create directory

Error message

Translation Writer was not able to create directory "%s".

What it means

When write() receives an options['path'], it tries @mkdir(path, 0777, true) if the directory does not exist. If creation fails (and the dir still doesn't exist), it throws this RuntimeException. @mkdir suppresses the PHP warning, so the exception is the only signal — typically a permissions problem on the parent directory.

Solutions

1. Create the directory beforehand with correct permissions: mkdir -p <path>
2. Verify the parent directory is writable by the PHP process user
3. Check that the path is not an existing file
4. Use a writable path in your config/CI environment

Example fix

// before
$writer->write($catalogue, 'xlf', ['path' => $config['output_dir']]);
// after
$dir = $config['output_dir'];
if (!is_dir($dir) && !@mkdir($dir, 0777, true)) {
    throw new RuntimeException("Cannot create output dir: $dir");
}
$writer->write($catalogue, 'xlf', ['path' => $dir]);

if (isset($options['path']) && !is_dir($options['path']) && !@mkdir($options['path'], 0777, true) && !is_dir($options['path'])) {
    throw new \RuntimeException("Output directory not writable: {$options['path']}");
}

try {
    $writer->write($catalogue, $format, $options);
} catch (\RuntimeException $e) {
    // handle directory creation failure: check permissions/disk space
    throw new \RuntimeException("Translation dump failed: ".$e->getMessage(), 0, $e);
}

When it happens

Trigger: write($catalogue, $format, ['path' => '/some/nonexistent/dir']) where the directory cannot be created: read-only filesystem, missing parent-directory permissions, disk full, or path exists as a file.

Common situations: Dumping translations in CI containers with read-only workspaces; wrong path configured in translation extraction config; trying to write into vendor/ or a root-owned directory.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Unable to create directory
• Loading translations from the Xliff format requires the…
• This is not a local file
• File " " not found.
• This is neither a file nor an XLIFF string

AI-assisted analysis of symfony/translation@ae9e8a51bc (2026-09-15). Data as JSON: /api/errors/a115190bb45915d9. Report an issue: GitHub.

Appendix: source

Thrown at Writer/TranslationWriter.php:65

    /**
     * Writes translation from the catalogue according to the selected format.
     *
     * @param string $format  The format to use to dump the messages
     * @param array  $options Options that are passed to the dumper
     *
     * @throws InvalidArgumentException
     */
    public function write(MessageCatalogue $catalogue, string $format, array $options = []): void
    {
        if (!isset($this->dumpers[$format])) {
            throw new InvalidArgumentException(\sprintf('There is no dumper associated with format "%s".', $format));
        }

        // get the right dumper
        $dumper = $this->dumpers[$format];

        if (isset($options['path']) && !is_dir($options['path']) && !@mkdir($options['path'], 0o777, true) && !is_dir($options['path'])) {
            throw new RuntimeException(\sprintf('Translation Writer was not able to create directory "%s".', $options['path']));
        }

        // save
        $dumper->dump($catalogue, $options);
    }
}

View on GitHub (pinned to ae9e8a51bc)