diff --git a/configs/development.ini b/configs/development.ini
--- a/configs/development.ini
+++ b/configs/development.ini
@@ -2,7 +2,6 @@
 
 ################################################################################
 ##                 RHODECODE COMMUNITY EDITION CONFIGURATION                  ##
-# The %(here)s variable will be replaced with the parent directory of this file#
 ################################################################################
 
 [DEFAULT]
@@ -103,6 +102,11 @@ use = egg:PasteDeploy#prefix
 prefix = /
 
 [app:main]
+## The %(here)s variable will be replaced with the absolute path of parent directory
+## of this file
+## In addition ENVIRONMENT variables usage is possible, e.g
+## sqlalchemy.db1.url = {ENV_RC_DB_URL}
+
 use = egg:rhodecode-enterprise-ce
 
 ## enable proxy prefix middleware, defined above
@@ -313,7 +317,7 @@ celery.task_always_eager = false
 #####################################
 ## Default cache dir for caches.  Putting this into a ramdisk
 ## can boost performance, eg. /tmpfs/data_ramdisk, however this directory might require
-## large ammount of space
+## large amount of space
 cache_dir = %(here)s/data
 
 ## `cache_perms` cache settings for permission tree, auth TTL.
@@ -353,7 +357,7 @@ rc_cache.sql_cache_short.expiration_time
 ## `cache_repo_longterm` cache for repo object instances, this needs to use memory
 ## type backend as the objects kept are not pickle serializable
 rc_cache.cache_repo_longterm.backend = dogpile.cache.rc.memory_lru
-# by default we use 96H, this is using invalidation on push anyway
+## by default we use 96H, this is using invalidation on push anyway
 rc_cache.cache_repo_longterm.expiration_time = 345600
 ## max items in LRU cache, reduce this number to save memory, and expire last used
 ## cached objects
@@ -503,10 +507,7 @@ appenlight.log_namespace_blacklist =
 ################################################################################
 #set debug = false
 
-
-##############
-## STYLING  ##
-##############
+# enable debug style page
 debug_style = true
 
 ###########################################
@@ -565,7 +566,7 @@ vcs.hooks.protocol = http
 vcs.hooks.host = 127.0.0.1
 
 vcs.server.log_level = debug
-## Start VCSServer with this instance as a subprocess, usefull for development
+## Start VCSServer with this instance as a subprocess, useful for development
 vcs.start_server = false
 
 ## List of enabled VCS backends, available options are:
diff --git a/configs/production.ini b/configs/production.ini
--- a/configs/production.ini
+++ b/configs/production.ini
@@ -2,7 +2,6 @@
 
 ################################################################################
 ##                 RHODECODE COMMUNITY EDITION CONFIGURATION                  ##
-# The %(here)s variable will be replaced with the parent directory of this file#
 ################################################################################
 
 [DEFAULT]
@@ -103,6 +102,11 @@ use = egg:PasteDeploy#prefix
 prefix = /
 
 [app:main]
+## The %(here)s variable will be replaced with the absolute path of parent directory
+## of this file
+## In addition ENVIRONMENT variables usage is possible, e.g
+## sqlalchemy.db1.url = {ENV_RC_DB_URL}
+
 use = egg:rhodecode-enterprise-ce
 
 ## enable proxy prefix middleware, defined above
diff --git a/rhodecode/config/middleware.py b/rhodecode/config/middleware.py
--- a/rhodecode/config/middleware.py
+++ b/rhodecode/config/middleware.py
@@ -540,10 +540,17 @@ def _string_setting(settings, name, defa
 
 
 def _substitute_values(mapping, substitutions):
-    result = {
-        # Note: Cannot use regular replacements, since they would clash
-        # with the implementation of ConfigParser. Using "format" instead.
-        key: value.format(**substitutions)
-        for key, value in mapping.items()
-    }
+
+    try:
+        result = {
+            # Note: Cannot use regular replacements, since they would clash
+            # with the implementation of ConfigParser. Using "format" instead.
+            key: value.format(**substitutions)
+            for key, value in mapping.items()
+        }
+    except KeyError as e:
+        raise ValueError(
+            'Failed to substitute env variable: {}. '
+            'Make sure you have specified this env variable without ENV_ prefix'.format(e))
+
     return result