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.

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 ''.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

• One or more environment variables failed assertions
• Expected either an instance of
• At least one environment file path must be provided.
• Conversion from encoding
• Failed to parse dotenv file.

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

Appendix: 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)