Unable to set the APP_PORT on .env for Laravel Sail

Unable to set the APP_PORT on .env for Laravel Sail

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Unable to set the APP_PORT on .env for Laravel Sail

The error services.laravel.test.ports contains an invalid type, it should be a number, or an object is a classic symptom of how Docker Compose handles variable substitution versus strict YAML typing. When you define APP_PORT=3000 in your .env file and reference it as ${APP_PORT:-80} in docker-compose.yml, the shell successfully substitutes the value. However, if that substitution results in a string representation or if the Docker Compose parser interprets the resulting line incorrectly based on whitespace, it fails validation before the container even starts.

In your specific setup with Laravel 8 and Sail, the docker-compose.yml file generated by php artisan sail:install relies heavily on environment variables to manage port mapping. The line - '${APP_PORT:-80}:80' is designed to be flexible. It maps the container's internal port 80 to whatever host port is defined in APP_PORT, defaulting to 80 if the variable is missing.

The core issue here is not that APP_PORT cannot exist; it is that the Docker Compose parser expects the substituted value to be a valid number immediately following the dash. If your environment variable contains unexpected characters, or if the file encoding introduces invisible artifacts, the parser rejects it. Furthermore, in Windows environments (specifically Windows 10), text editors like Notepad or sometimes even VS Code can introduce carriage returns (\r) or different line ending styles that confuse Docker Compose's strict YAML validation, whereas Ubuntu often handles these differently by default.

To resolve this without modifying the docker-compose.yml file—which is critical given your team workflow and the risk of sail:install overwriting your changes—you must ensure the .env variable is clean and strictly numeric.

First, verify your .env file using a hex editor or by checking the raw bytes. Ensure there are no trailing spaces after 3000 in the line APP_PORT=3000. Even a single space can cause YAML parsers to treat the value as invalid when substituted.

If the variable is clean, the next step involves how Docker Compose interprets the port mapping. The syntax - '${APP_PORT:-80}:80' expects ${APP_PORT} to resolve to an integer. If you are on Windows, try saving the .env file with UTF-8 BOM removed. Some versions of Docker for Windows or specific editors add a Byte Order Mark (BOM) that breaks shell variable expansion in certain contexts. Open your .env file in a text editor like Notepad++, search for APP_PORT, and ensure it looks exactly like this:

APP_PORT=3000

No spaces, no tabs, just the key, an equals sign, and the number.

If that does not resolve the issue, consider how Docker Compose handles variable interpolation in port definitions. While ${VAR} is standard, sometimes the parser struggles with the string conversion if the variable is treated as a string type in specific shell environments. A robust workaround, which keeps your docker-compose.yml untouched but ensures compatibility, is to use a temporary file to inject the correct port mapping without altering the main compose file permanently. However, since you want to avoid editing docker-compose.yml, the most direct fix is ensuring the environment variable is recognized as an integer by the shell before Docker sees it.

You can force this by exporting the variable in your terminal session before running sail up:

export APP_PORT=3000

Then run:

sail up

This bypasses potential issues where the .env file parser might be reading the value differently than a direct shell export. If this works, the issue lies in how the specific version of Sail or your Windows environment is parsing the .env file relative to Docker Compose's expectations.

Remember that sail:install will regenerate docker-compose.yml. To protect your configuration permanently without editing the YAML directly, you can rely on a .env approach that is resilient to parser quirks. If APP_PORT=3000 consistently fails on Windows but works on Ubuntu, it is almost certainly a line-ending or encoding issue specific to your local environment. Switching to Unix-style line endings (LF) instead of Windows-style (CRLF) in the .env file often resolves these type mismatches in Docker Compose validation.

By cleaning the .env file, ensuring no BOM is present, and forcing a shell export before invoking Sail, you maintain your workflow integrity while satisfying Docker's strict typing requirements for port mappings. This approach respects your team's constraints and avoids the fragility of hardcoding ports in the YAML file itself.

Our network