vlucas/phpdotenv · error · InvalidArgumentException

Expected name to be a non-empty string.

Error message

Expected name to be a non-empty string.

What it means

AdapterRepository::get() (src/Repository/AdapterRepository.php:65) rejects the empty string as a variable name before any adapter is consulted, throwing InvalidArgumentException. The repository API treats '' as a programming error in the caller, not as 'variable not found' — a missing variable returns null, an empty name never reaches the readers. It is a hard precondition guard on the name argument only; the value is not involved.

Source

Thrown at src/Repository/AdapterRepository.php:65

     */
    public function has(string $name)
    {
        return '' !== $name && $this->reader->read($name)->isDefined();
    }

    /**
     * Get an environment variable.
     *
     * @param string $name
     *
     * @throws \InvalidArgumentException
     *
     * @return string|null
     */
    public function get(string $name)
    {
        if ('' === $name) {
            throw new InvalidArgumentException('Expected name to be a non-empty string.');
        }

        return $this->reader->read($name)->getOrElse(null);
    }

    /**
     * Set an environment variable.
     *
     * @param string $name
     * @param string $value
     *
     * @throws \InvalidArgumentException
     *
     * @return bool
     */
    public function set(string $name, string $value)
    {
        if ('' === $name) {

View on GitHub (pinned to 416df70283)

Solutions

1. Log or dump the name at the call site to find which computation produced ''.
2. Filter and trim the list before use: array_filter(array_map('trim', $names), fn ($n) => $n !== '').
3. Fix the upstream source: remove trailing commas, correct the config key, skip empty entries when building names.
4. Add a guard that skips (or explicitly handles) empty names before calling get().

Example fix

// before
foreach (explode(',', $config['copy_vars']) as $name) {
    $value = $repository->get($name);
}

// after
foreach (array_filter(array_map('trim', explode(',', $config['copy_vars'] ?? ''))) as $name) {
    if ($name !== '') {
        $value = $repository->get($name);
    }
}

// Guard a dynamically built name before lookup:
$name = trim((string) ($config['var_name'] ?? ''));
if ($name === '') {
    return null; // or log and skip this entry
}
$value = $repository->get($name);

function isNonEmptyEnvName(mixed $name): bool
{
    return is_string($name) && $name !== '';
}

When it happens

Trigger: $repository->get('') — almost always a computed name: a config key that is absent or mistyped and coalesces to ''; explode(',', $csv) producing '' from a trailing comma; str_replace/preg_replace stripping the whole name; a loop over array keys that contain an empty element.

Common situations: Iterating a configurable list of variable names (feature flags, cache purgers); names built as $prefix.$suffix where one part is empty; tests seeding/fetching variables from fixtures; a typo'd config key returning null that strict coercion turns into ''.

Related errors

• One or more environment variables failed assertions: %s.
• Expected either an instance of %s or a class-string implemen
• Failed to parse dotenv file. %s
• Illegal character encoding [%s] specified.
• Conversion from encoding [%s] failed.

AI-assisted analysis of vlucas/phpdotenv@416df70283 (2026-08-21). Data as JSON: /api/errors/ed45a001afb3b8e8. Report an issue: GitHub.