FAQ
Basic Usage
Should I choose Load() or New()?
env.Load() (global mode) suits simple applications: load once, then use package-level functions. It applies variables to the process environment.
env.New() (instance mode) suits tests and multi-configuration programs: it creates an isolated instance, applies nothing unless cfg.AutoApply = true, and requires an explicit Close().
// Simple application → global mode
env.Load(".env")
port := env.GetInt("PORT", 8080)
// Testing / multi-configuration → instance mode
loader, _ := env.New(env.TestingConfig())
defer loader.Close()
loaderPort := loader.GetInt("PORT", 8080)How to choose
Start with env.Load(). Switch to env.New() when you need test isolation or more than one configuration at a time.
Why can Load() only be called once?
Load() sets the default loader, and a second call returns ErrAlreadyInitialized. The restriction prevents a later load from silently replacing configuration that is already in use.
// First call: succeeds
env.Load(".env")
// Second call: returns an error
err := env.Load(".env.production")
// err == env.ErrAlreadyInitializedSolutions:
// Solution 1: Load multiple files at once (recommended)
env.Load(".env", ".env.production")
// Solution 2: Reset first when re-initialization is needed (mainly for tests)
if err := env.ResetDefaultLoader(); err != nil {
log.Printf("warning: failed to reset loader: %v", err)
}
env.Load(".env.production")What happens when the .env file doesn't exist?
The default is to skip a missing file without an error, which supports the "load if present, ignore if absent" deployment pattern.
// DefaultConfig: skips a missing file
env.Load(".env", ".env.local")
// No error even when neither file existsTo get an error instead (recommended in production):
cfg := env.ProductionConfig()
// FailOnMissingFile is true in this preset
loader, _ := env.New(cfg)How to access nested JSON/YAML values?
Nested JSON/YAML structures are flattened to underscore-separated key names:
{
"database": {
"host": "localhost",
"port": 5432
}
}Stored as: DATABASE_HOST=localhost, DATABASE_PORT=5432The three forms are equivalent; distinct names only illustrate them:
nameFlat := env.GetString("DATABASE_HOST") // Flat key (recommended)
nameDot := env.GetString("database.host") // Dot path
nameUpper := env.GetString("DATABASE.HOST") // Uppercase dot pathThe full conversion table is in Multi-format Config · Key Resolution.
Types and Generics
Why is GetSlice a generic function instead of a method?
Go does not support type parameters on methods. GetSlice[T] must be a function, not a method:
// ❌ Method approach — compile error (Go doesn't support this)
// loader.GetSlice[int]("PORTS")
// ✅ Function approach — works
env.GetSliceFrom[int](loader, "PORTS")
// ✅ Package-level function
env.GetSlice[int]("PORTS")How does GetSlice parse slice values?
Two sources are tried in order:
- Indexed keys (recommended):
KEY_0,KEY_1,KEY_2... - Comma-separated:
KEY=val1,val2,val3
# Method 1: Indexed keys
HOSTS_0=localhost
HOSTS_1=example.com
# Method 2: Comma-separated
HOSTS=localhost,example.comhosts := env.GetSlice[string]("HOSTS") // ["localhost", "example.com"]What boolean value formats are supported?
GetBool is case-insensitive and accepts these values:
| Truthy | Falsy |
|---|---|
true, 1, yes, on, enabled | false, 0, no, off, disabled |
An empty string parses as false rather than falling back to the default. Any other value is audited and returns the default.
Concurrency and Thread Safety
Can I call Get from multiple goroutines simultaneously?
Yes. All Loader methods are thread-safe. Sharded locks keep read and write contention low under concurrency.
// Safe concurrent access
var wg sync.WaitGroup
for i := 0; i < 100; i++ {
wg.Add(1)
go func() {
defer wg.Done()
_ = env.GetString("KEY") // Thread-safe
}()
}
wg.Wait()A Loader instance (not just the package-level functions) can be shared the same way; see Concurrency & Lifecycle.
What happens when calling Get after Loader.Close()?
Getters return zero values and do not panic. Writes return ErrClosed.
loader, _ := env.New()
defer loader.Close()
val := loader.GetString("KEY") // Returns a value
// After Close()
val = loader.GetString("KEY") // Returns "" (zero value)
err := loader.Set("KEY", "v") // Returns ErrClosed
_ = val
_ = errSecureValue
What's the difference between Release and Close?
Release() zeroes the value, unlocks the memory, and returns the object to the pool; Close() zeroes and unlocks but does not return it to the pool. Use Release() by default. For the full comparison see Memory Locking · Prefer Release Over Close.
Does SecureValue auto-zero when garbage collected?
Yes. SecureValue installs a finalizer that zeroes the memory during garbage collection. Call Release() or Close() explicitly anyway, so cleanup happens at a known time instead of whenever the GC runs.
// ✅ Recommended: explicit release
sv := env.GetSecure("API_KEY")
defer sv.Release()
// ⚠️ Relying on GC: safe but not timely
svNoRelease := env.GetSecure("API_KEY")
_ = svNoRelease // no Release call; the GC finalizer zeroes it eventuallyHow to safely log?
Use Masked() or the masking functions, and never print a Reveal() value:
sv := env.GetSecure("API_KEY")
defer sv.Release()
// ✅ Safe: masked output
log.Printf("API Key: %s", sv.Masked()) // [SECURE:32 bytes]
log.Printf("API Key: %s", sv) // Same (String() returns Masked())
// With memory locking disabled there is no status suffix; locking enabled and
// successful yields [SECURE:32 bytes locked]
// ✅ Safe: masking functions
masked := env.MaskValue("API_KEY", "sk-xxx") // [MASKED] (sensitive key → fixed mask)
clean := env.SanitizeForLog(logMessage) // Auto-detect and mask
// ❌ Dangerous: plaintext leak
plaintext := sv.Reveal()
log.Printf("API Key: %s", plaintext) // Don't do thisConfiguration and Validation
How to load only variables with a specific prefix?
Use the Prefix field to filter:
cfg := env.DefaultConfig()
cfg.Prefix = "MYAPP_" // Only load variables starting with MYAPP_
loader, _ := env.New(cfg)
loader.LoadFiles(".env")# .env file content
MYAPP_HOST=localhost # ✅ Loaded
MYAPP_PORT=8080 # ✅ Loaded
OTHER_KEY=value # ❌ Ignored (no MYAPP_ prefix)How to prevent configuration overrides?
OverwriteExisting controls whether Set and file loads replace a key that already exists:
// Default: no overwriting (safe)
cfg := env.DefaultConfig()
cfg.OverwriteExisting = false
// Development: allow overwriting
cfg = env.DevelopmentConfig()
// OverwriteExisting = trueWhen does RequiredKeys validation execute?
Required keys are checked once when parsing or loading finishes: loader.LoadFiles(...) returns validation error on field "required_keys": missing required keys: ... when a key is missing, and env.New(cfg) returns the same error when Filenames is non-empty. Validate() then checks the current store again, which is useful after setting extra values post-load:
cfg := env.ProductionConfig()
cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}
cfg.Filenames = nil // loaded explicitly below
loader, err := env.New(cfg)
if err != nil {
log.Fatal(err)
}
// Checked when loading finishes
if err := loader.LoadFiles(".env"); err != nil {
if errors.Is(err, env.ErrMissingRequired) {
log.Fatal("Missing required environment variables")
}
}
// Explicit validation: checks the current store again
if err := loader.Validate(); err != nil {
if errors.Is(err, env.ErrMissingRequired) {
log.Fatal("Missing required environment variables")
}
}Testing
How to isolate the environment in tests?
Use TestingConfig() with an independent Loader instance per test:
func TestConfig(t *testing.T) {
cfg := env.TestingConfig()
cfg.OverwriteExisting = true
loader, err := env.New(cfg)
if err != nil {
t.Fatal(err)
}
defer loader.Close()
// Each test gets its own loader
loader.Set("KEY", "test-value")
val := loader.GetString("KEY")
// Test...
}How to reset global mode tests?
Use ResetDefaultLoader():
func TestGlobalMode(t *testing.T) {
// Clean up previous test state
if err := env.ResetDefaultLoader(); err != nil {
t.Logf("reset default loader: %v", err)
}
defer func() {
if err := env.ResetDefaultLoader(); err != nil {
t.Logf("reset default loader: %v", err)
}
}()
env.Load(".env.test")
// Test...
}Full testing guide
See the Testing guide.
Security and Lifecycle
Are process-environment variables still there after Close?
Yes. Close() zeroes and unlocks the in-memory copies; it does not unset variables previously applied to the process environment. Removing them is deliberate caller work: the environment may already have been inherited by child processes, so automatic rollback is not attempted. Call Delete per key before closing; only keys this loader wrote get unset. ResetDefaultLoader() also leaves applied variables in place.
How do I stop a configuration file from reading process secrets?
When a configuration file comes from an untrusted source (user uploads, external delivery), an expansion scope that lets ${VAR} fall back to the process environment can capture secrets into variable values. DefaultConfig() already selects the file-only scope (ExpansionFileOnly), which blocks that fallback; the assignment below states the default explicitly:
cfg := env.DefaultConfig()
cfg.ExpansionScope = env.ExpansionFileOnly // ${VAR} resolves file-local variables only (already the default)See Variable Expansion · Expansion Scope.
Why did the $ in my value change when read back?
ExpandVariables is enabled by default, so $VAR and ${VAR} sequences are expanded at load time. If a value contains literal dollar signs (prices, template strings), load it with cfg.ExpandVariables = false. Marshal output is not affected by this: the library escapes $ as \$, so a Marshal → load round trip does not re-expand. See Serialization.
Related Documentation
- Quick Start - 5-minute introduction
- Cheat Sheet - high-frequency snippets
- Error Handling - sentinel errors and recovery strategies
- File Format - .env/JSON/YAML syntax