env.php is small, sensitive, and easy to misread
The app/etc/env.php file tells Magento how to connect to the services around the store. It is small, but a bad value can stop the application or make it use the wrong service.
The file holds database credentials, cache and session backends, deploy mode, and the encryption key. It is one of the first files to inspect when a deployment behaves differently from the environment used to test it.
Configuration problems get confusing when env.php, config.php, and the database contain different values. The admin can show one value while Magento uses another. You need to know which source wins before changing anything.
What env.php controls
The app/etc Directory contains environment-specific settings. The exact entries vary by Magento version and installed modules, but the file commonly controls these parts of the application:
- Database connection details, including host, name, and credentials.
- Cache and session backends, such as Redis or Valkey configuration.
- The deploy mode, through
MAGE_MODE. - The encryption key, used for encrypting stored credentials and sensitive data.
- The list of enabled cache types.
These values belong to the environment, not to the application code. Production and staging usually have different database hosts, passwords, cache endpoints, and encryption keys. That is why app/etc/env.php normally stays out of version control.
Keep the file in the expected Directory and make sure the PHP process can read it. A correct file in the wrong path is still a broken deployment.
The encryption key travels with the database
Magento uses the encryption key to protect values stored in the database. Those values can include payment credentials, integration secrets, and other sensitive configuration.
The key belongs in the backup plan. Store it in a protected secret system and keep it with the database backup it can decrypt. A database copy without the matching key is only a partial copy because some stored values are unreadable.
Do not replace the key casually. Generating a new key does not automatically convert every old encrypted value. If a key is exposed, treat the event as a credential incident and follow a tested key-rotation process that re-encrypts affected values.
Magento has a configuration override order
Magento can read a setting from the database, app/etc/config.php, or app/etc/env.php. The database stores scope values in core_config_data. config.php stores shared configuration in code. env.php stores environment-specific values.
For the same setting, the usual priority order is env.php, then config.php, then the database. The higher-priority source wins. An environment value in env.php can override a database value. A locked value in config.php can also prevent an admin change from taking effect.
This explains the common report, "I changed it in the admin and nothing happened." The admin saved a new database value, but Magento read a higher-priority value from a deployment file.
Read the files and the database before changing the setting again. Otherwise, you may edit the lower-priority source and get the same result.
Scope drift hides the value you are testing
Magento stores many settings at a scope. A value can exist at the default level, the website level, or the store-view level. For a particular store, the most specific value applies.
For example, the default scope can contain one base URL while a website scope contains another. Looking only at the default row gives you the wrong answer for that website. The store-view scope can override it again.
Scope drift happens when several levels contain different values and nobody records which level is intentional. This is common after a second website or store view is added, or after an environment is copied.
Run bin/magento config:show to inspect the effective value and its scope. Use the output to find the setting Magento actually reads instead of guessing from the admin screen.
config.php can lock a setting
Running bin/magento app:config:dump writes deployable configuration to the configuration files. Shared values can go into app/etc/config.php, while environment-specific values belong in app/etc/env.php. Magento versions and command options affect the exact output, so check the command behavior for the version you run.
Use the --lock-config option when config.php values must be read-only in the admin. Use --lock-env when environment values in env.php must be locked there. A locked value cannot be changed from the admin because Magento expects the value to come from code and deployment.
Locking works well for settings that should match across environments. It causes avoidable confusion when the team does not document the lock. An admin user sees a read-only field and has no way to know that the next change belongs in a configuration file or deployment process.
Review the resulting DIFF before deploying a dump. A configuration dump can include more settings than the one you intended to change.
Keep env.php out of exposed locations
Because env.php contains credentials and the encryption key, its file permissions must limit access. The PHP process needs to read it. Other users and web requests should not.
Never make it world-readable, place it in a web-accessible backup Directory, or serve it as a download. Test the web server configuration so a request cannot return the PHP source if PHP handling fails.
A copy in a shared drive, ticket, chat message, or unprotected backup is a credential exposure. The file can contain everything needed to connect to the database and other services.
If env.php is exposed, rotate the database and service credentials according to your incident plan. Do not assume deleting the exposed copy fixes the problem.
Diagnose the source before changing the value
When a setting behaves unexpectedly, check the sources in priority order. Start with app/etc/env.php. Then inspect app/etc/config.php. Finally check core_config_data and its scope with bin/magento config:show.
Do not paste the full contents of env.php into a ticket or chat while investigating. Read only the key names and compare secret values through a protected channel.
The effective value comes from the highest-priority source that defines it. This turns "why is this setting this value?" into a short lookup instead of a long series of admin changes.
Repeat the same check on staging and production. If the two environments resolve the setting differently, record whether the difference comes from env.php, config.php, or a database scope. That record gives the next deployment a Reproducible explanation.
Review env.php before the next deployment
A wrong deploy mode, a lost encryption key, or a silent override can consume hours. The file is easy to ignore because it rarely changes during normal feature work.
Review app/etc/env.php, app/etc/config.php, and the relevant core_config_data scopes together. Confirm that the database host, cache backend, session backend, encryption key, and locked settings belong to the environment where they will run.
Keep the review in the deployment record, protect the secrets, and compare a DIFF for code-managed configuration. That small check catches path drift and override problems before Magento has to reveal them in production.