apify/crawlee · error · Error

Cannot open storage with alias "${alias}" because a named st

Error message

Cannot open storage with alias "${alias}" because a named storage with the same identifier already exists.

What it means

StorageInstanceManager throws this when opening a storage with an `alias` that collides with an already-open named storage of the same class and backend cache key. Names and aliases share one identifier space per storage type, so an alias cannot shadow an existing explicit name.

Source

Thrown at packages/core/src/storages/storage_instance_manager.ts:132

                        keyMap.delete(cacheKey);
                    }
                }
            }
        }
    }

    /**
     * Ensure that the same string is not used as both a name and an alias for the same
     * storage class + backend combination. Mirrors crawlee-python's `_check_name_alias_conflict`.
     */
    checkNameAliasConflict<T extends IStorage>(
        cls: Constructor<T>,
        { name, alias, backendCacheKey }: { name?: string; alias?: string; backendCacheKey: Hashable },
    ): void {
        if (alias) {
            const existingByName = this.byName.get(cls)?.get(alias)?.get(backendCacheKey);
            if (existingByName) {
                throw new Error(
                    `Cannot open storage with alias "${alias}" because a named storage with the same identifier already exists.`,
                );
            }
        }
        if (name) {
            const existingByAlias = this.byAlias.get(cls)?.get(name)?.get(backendCacheKey);
            if (existingByAlias) {
                throw new Error(
                    `Cannot open storage with name "${name}" because an alias storage with the same identifier already exists.` +
                        ` If you meant to open the alias storage, use { alias: "${name}" } instead.`,
                );
            }
        }
    }

    /** Iterate all cached instances across all storage types. */
    *allValues(): IterableIterator<IStorage> {
        const seen = new Set<IStorage>();

View on GitHub (pinned to dbe57fb09c)

Solutions

Rename the alias to a unique value
Use the existing named storage instead of opening an alias
Call open with { name: alias } (the name form) if you intend to reuse the named storage
Audit all open() call sites to consistently use either name or alias

Example fix

// before
await RequestQueue.open({ name: 'my-queue' });
await RequestQueue.open({ alias: 'my-queue' }); // throws
// after
await RequestQueue.open({ name: 'my-queue' });
await RequestQueue.open({ alias: 'my-queue-alt' });

Defensive patterns

Strategy: validation

Validate before calling

function assertNoNameAliasConflict(openOpts) {
  if (openOpts.alias && openedNames.has(openOpts.alias)) {
    throw new Error(`Alias "${openOpts.alias}" collides with an existing named storage`);
  }
}

Type guard

null

Try / catch

try {
  store = await RequestQueue.open({ alias });
} catch (err) {
  if (/alias .* because a named storage/.test(String(err))) {
    store = await RequestQueue.open({ name: alias });
  } else throw err;
}

Prevention

Standardize on one identifier convention (name xor alias) per project
Keep a registry of opened storage identifiers in shared code
Use unique prefixes per module for storage identifiers

When it happens

Trigger: Calling e.g. RequestQueue.open({ alias: 'foo' }) (or KeyValueStore/Dataset equivalents) after RequestQueue.open({ name: 'foo' }) was already opened in the same process with the same backend.

Common situations: Refactoring code from named to aliased storages while old named opens still run; mixing config styles across modules where one module uses name and another alias for the same logical storage.

Related errors

AI-assisted analysis of apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/5a599716029a0707. Report an issue: GitHub.