"Unable to resolve service" in production only after enabling laminas config cache

Direct answer

A stale merged-config cache is the most likely cause of the production-only Unable to resolve service error. Missing *.local.php overrides typically produce different symptoms (missing values, wrong credentials) and rarely break factory resolution for services defined in a module's own configuration.

Laminas-modulemanager has no built-in automatic cache invalidation. The documented and community-accepted practice is to delete data/cache on every deploy. Since laminas-modulemanager 3.5+, you can also set a custom config_cache_key (e.g., a git commit hash) to version the cache without manual deletion.

Cache behavior is stable across 2.x and 3.x releases; the only version-dependent feature is the config_cache_key option introduced in 3.5. Verify your pinned version to know which strategy is available.

Why the stale cache explains the error

The merged-config cache serializes the complete ServiceManager configuration (factories, aliases, initializers). When a module adds, moves, or renames a factory but the cache is not cleared, the ServiceManager reads the outdated definition and cannot resolve the service. This only appears in production because config_cache_enabled is true there and false locally.

Missing *.local.php files are a secondary suspect

Local overrides usually affect environment-specific values (database DSN, API keys). They do not remove factory definitions that come from a module's module.config.php. If the missing service's factory is defined in the module itself, the absence of *.local.php files will not cause this error.

Supported cache invalidation mechanisms

1. Manual deletion (all versions): Remove data/cache/* after composer install and before serving traffic.
2. Versioned cache key (laminas-modulemanager ≥ 3.5): Set 'config_cache_key' => getenv('DEPLOY_VERSION') ?: 'default' in module_listener_options and pass a unique value per release (e.g., DEPLOY_VERSION=$(git rev-parse HEAD)).

Disabling config_cache_enabled in production is not recommended; merging configuration on every request has a measurable performance cost.

Version check and verification steps

# Check laminas-modulemanager version
composer show laminas/laminas-modulemanager

# Inspect the cached config (replace 'production' with your environment)
cat data/cache/module-config-cache.production.php | grep -n 'service_name'

# Clear cache manually (if not using config_cache_key)
rm -rf data/cache/*

Deployment checklist

• Run composer install --no-dev.
• Clear data/cache or ensure a unique config_cache_key is provided.
• Confirm modules.config.php is up to date.
• Warm the cache if your deployment script boots the application (optional but recommended).
• Verify opcache is not serving stale PHP files (opcache.validate_timestamps=0 requires restart or cache clear on deploy).

One diagnostic detail that could change the recommendation

If the missing service's factory is defined inside a closure that reads an environment variable only set locally, the error would persist even with a fresh cache. Check whether getConfig() in the module returns a closure that behaves differently per environment.