Why String.fromEnvironment() Might Return an Empty String in Dart

A complete guide to why String.fromEnvironment() silently returns an empty string when used with final, what Dart is actually doing under the hood, and how to structure your environment configuration so it can never happen again, from local development all the way to production builds.

I ran into this issue myself while working on a service class where I used String.fromEnvironment() with a final variable to read my API base URL. Everything compiled successfully, there were no warnings, and the code looked perfectly valid. But when the app ran, the value kept resolving to an empty string. Nothing explicitly failed, the application simply behaved as if the configuration was missing.

The only way I was able to trace the issue was through debugging, where I eventually discovered what Dart was actually doing under the hood. If you have ever experienced a mysteriously empty environment variable or want to make sure this subtle bug never happens in your project, this article is for you.

final vs const

Both final and const prevent a variable from being reassigned after it has been given a value. That is the only similarity between them. Apart from that, they behave differently in almost every other way.

final — assigned once at runtime

A final variable is assigned once and cannot be changed after that. However, its value is determined at runtime when the code is executed. This means the value can come from a function call, a network response, user input, or any other data available while the app is running.

// All of these are valid final assignments
final timestamp = DateTime.now();          // computed at runtime
final name = prefs.getString('name');      // read from disk at runtime
final url = computeBaseUrl();              // result of a function at runtime

const — a compile-time constant

A const value must be fully determined before the app is compiled. The Dart compiler evaluates it, checks it, and embeds the result directly into the compiled binary. It does not exist as a runtime object in memory. Instead, it is stored as a fixed literal inside the generated machine code.

// These are compile-time constants
const pi = 3.14159;
const appName = 'Clock App';
const timeout = Duration(seconds: 30);

// This is NOT valid, DateTime.now() is only known at runtime
const now = DateTime.now(); // compile error

String.fromEnvironment()

Looking at the Dart SDK source, String.fromEnvironment() is declared like this:

// From the Dart SDK — dart:core
abstract class String {
  external const factory String.fromEnvironment(
    String name, {
    String defaultValue = '',
  });
}

Three things in that signature matter enormously:

• const factory — it is a const constructor. The Dart spec says a const constructor can only produce a meaningful value when called in a const context.
• external — the actual implementation is provided by the compiler toolchain, not by Dart code. When the compiler sees a const invocation, it substitutes the value from --dart-define. There is no runtime implementation that reads environment variables.
• defaultValue: '' — if the compiler finds no substitution to make, it uses the default. Silently. No error, no warning.

String.fromEnvironment does not actually read any values at runtime. It is a compiler directive that looks like a constructor call. During compilation, the Dart compiler replaces it with a plain string literal. By the time the app runs, there is no special logic left, only the final string value as if it had been written directly in the source code.

The two evaluation paths

When the Dart compiler encounters String.fromEnvironment('UPLOAD_URL'), it takes one of two paths depending on the call context:

1. Call is in a const context
   The compiler looks up UPLOAD_URL in the --dart-define flags. If found, it substitutes the literal string value into the binary. If not found, it substitutes '' (the default). Either way, the value is resolved at at compile time.

2. Call is in a final or non-const context
   The compiler sees a regular constructor call and defers it to runtime. At runtime there is no mechanism to read --dart-define flags because those were consumed during compilation. The constructor returns its defaultValue, which is ''. Every single time.
   

// What the compiler does with const:
static const baseUrl = String.fromEnvironment('UPLOAD_URL');
//  compiler substitutes at build time
static const baseUrl = 'https://upload.example.com';

// What happens with final:
static final baseUrl = String.fromEnvironment('UPLOAD_URL');
//  deferred to runtime  --dart-define is gone
static final baseUrl = ''; // defaultValue returned every time

Why it is so hard to debug: static final compiles without error. The analyser produces no warning. Your app launches normally. The empty string only surfaces when a network request silently fails, far from the actual cause, with no stack trace pointing back to the declaration.

The same rule applies to all three environment constructors

This is not specific to String.fromEnvironment. All three environment constructors in Dart share the same external const factory signature and behave identically:

Type	Method	Description	Default Value
String	String.fromEnvironment('KEY', defaultValue: '')	Reads a string value from environment variables	'' (empty string)
bool	bool.fromEnvironment('KEY', defaultValue: false)	Reads a boolean value from environment variables	false
int	int.fromEnvironment('KEY', defaultValue: 0)	Reads an integer value from environment variables	0

All three must be called in a const context to produce any value other than their default. Using final with any of them gives you the default silently.

// Every one of these will silently return its default with 'final'
static final apiUrl    = String.fromEnvironment('API_URL');     // ''
static final debugMode = bool.fromEnvironment('DEBUG_MODE');   // false
static final version   = int.fromEnvironment('APP_VERSION');   // 0

// All three correct with 'const'
static const apiUrl    = String.fromEnvironment('API_URL');     // your URL
static const debugMode = bool.fromEnvironment('DEBUG_MODE');   // true/false
static const version   = int.fromEnvironment('APP_VERSION');   // your int

This is written in the String.fromEnvironment documentation:

This constructor is only guaranteed to work when invoked as const. It may work as a non-constant invocation on some platforms which have access to compiler options at run-time, but most ahead-of-time compiled platforms will not have this information.

How to structure your environment config correctly

Rather than spreading String.fromEnvironment calls across your codebase where any of them could mistakenly use final, keep all environment access in one place. Create a single class responsible for it and ensure this is the only place in your entire project where fromEnvironment is used.

abstract class AppEnv {

  // API endpoints 
  static const apiBaseUrl = String.fromEnvironment('API_BASE_URL');
  static const uploadUrl = String.fromEnvironment('UPLOAD_URL');
  static const socketUrl = String.fromEnvironment('SOCKET_URL');

}

Because the class is abstract, it cannot be instantiated. Every field is static const, which makes misuse (calling them on an instance, or shadowing them with final) structurally impossible. Any other service in the project references it directly:

// lib/core/network/upload_service.dart

class UploadService {
  // No fromEnvironment call here, always go through AppEnv
  static const _baseUrl = AppEnv.uploadUrl;

  static Future<dynamic> request({ ... }) async {
    final uri = Uri.parse('$_baseUrl$endpoint');
    // ...
  }
}

Enable the lint rule so the analyser catches this automatically

Dart's prefer_const_declarations lint rule will flag any final variable whose value is a compile-time constant, including all three fromEnvironment constructors. This turns a silent runtime bug into a compile-time analyser warning.

# analysis_options.yaml
linter:
  rules:
    prefer_const_declarations: true
    prefer_const_constructors: true
    prefer_const_literals_to_create_immutables: true

This will immediately show a warning in your IDE:

//  Lint: Prefer const with constant initialized variables.
// Replace 'final' with 'const'.
static final baseUrl = String.fromEnvironment('UPLOAD_URL');

The env file setup

Correct file structure
The file must be a flat JSON object. No nesting. Keys match exactly what you pass to fromEnvironment.

// env.json - flat, no nesting, exact key names
{
  "API_BASE_URL": "https://api.example.com",
  "UPLOAD_URL": "https://upload.example.com",
  "SOCKET_URL": "wss://socket.example.com",
  "BUILD_ENV": "production",
  "ENABLE_ANALYTICS": "true",
}

Note: All values in the JSON must be strings including booleans and integers. Dart's toolchain reads them as strings and performs the type conversion internally. "false" not false, "12" not 12.

The four rules to remember

#	Rule	Description
1	Always const	fromEnvironment is a compiler directive. Use static const. Always. No exceptions.
2	Centralise	Call fromEnvironment in exactly one file (AppEnv). Everywhere else imports from there.
3	Enable the lint	Add prefer_const_declarations: true to analysis_options.yaml. Let the analyser enforce rule 1.
4	Flat JSON	Your env.json must be a flat { "KEY": "value" } object. No nesting. All values are strings.