Docker environment setup fails with: docker-compose file is malformed
Deployrr keeps one main compose file in your Docker folder. It is named docker-compose-HOSTNAME.yml, where HOSTNAME is the name of your machine. This page helps when Deployrr says that file is malformed, or when it reports a compose file error.
Symptoms
Section titled “Symptoms”You run Prerequisites > Environment (Setup Docker Environment). Deployrr gets to the “Creating starter compose files…” step and stops with an error like this:
/home/USERNAME/docker/docker-compose-HOSTNAME.yml is malformed (missing placeholders)Deployrr then points you to the documentation and says you can generate a troubleshooting log from the Settings menu.
You can see the same message after installing Socket Proxy or Deployrr Dashboard from the Docker menu. Both installs check the main compose file when they finish. Other app installs don’t run this check.
A different problem shows up in Tools > Diagnostics:
- The YAML Yoda line says “One or more compose files has errors”.
- YAML Yoda shows a “Compose Validation Error” box with the file and Docker’s message.
That is a YAML syntax error. See Find a YAML error below.
The main compose file has four lines that Deployrr uses to add your apps. If any of them is missing or changed, Deployrr calls the file malformed. They are:
# NETWORKS-PLACEHOLDER-DO-NOT-DELETE # SECRETS-PLACEHOLDER-DO-NOT-DELETEinclude: # SERVICE-PLACEHOLDER-DO-NOT-DELETEinclude: starts at the beginning of its line. The three comment lines start with two spaces. Each line must be on its own, with nothing else on it. Extra text or different indentation counts as missing.
To understand how a main compose file is laid out, watch Docker Compose walkthrough: networks, include and YAML spacing at 14:02 (manual Docker Compose setup with different folder and file names; Deployrr does these steps for you, and its file also has the placeholder lines).
When the error comes from Prerequisites > Environment, Deployrr has just copied in a fresh starter file and checked it, so your own edits are not the cause. The starter file it copied is damaged. Use Option 2, and ask on Discord if it fails again.
When the error comes after a Socket Proxy or Deployrr Dashboard install, the usual cause is a hand edit that removed or changed one of the lines. Use Option 1.
Option 1: Put the lines back by hand (keeps your apps)
Section titled “Option 1: Put the lines back by hand (keeps your apps)”-
Make a copy of the file first. Run this in your Docker folder:
Terminal window cp docker-compose-$HOSTNAME.yml docker-compose-$HOSTNAME.yml.bak -
Open
docker-compose-HOSTNAME.ymlin a text editor. -
Compare it with the layout of a fresh file. Missing lines go in these places:
networks:default:driver: bridge# (your other networks)# NETWORKS-PLACEHOLDER-DO-NOT-DELETE# secrets:# (your secrets)# SECRETS-PLACEHOLDER-DO-NOT-DELETEinclude:# (your app lines, such as - compose/$HOSTNAME/sonarr.yml)# SERVICE-PLACEHOLDER-DO-NOT-DELETEEach placeholder goes at the end of its section. Keep your own lines above it. Watch for spaces at the end of a placeholder line; they count as extra text.
-
Check the
include:list. Apps you installed while a placeholder was missing were never added to it, and Deployrr didn’t warn you. Every app file incompose/HOSTNAME/needs a line like- compose/$HOSTNAME/sonarr.ymlabove the service placeholder. Type$HOSTNAMEas written, not your machine’s name. -
Save the file.
-
Run the Socket Proxy or Deployrr Dashboard install again from the Docker menu. Deployrr shows an Already Installed box. Choose yes. It recreates the container and keeps its data. This time the check passes.
Option 2: Rebuild the file with the Environment step
Section titled “Option 2: Rebuild the file with the Environment step”Use this if the file is badly damaged or you have no apps yet. A rebuild always replaces the main compose file and custom.yml with fresh starter files.
- Back up first. With a Pro license, use Tools > Backups > Backup (see Back up and restore your Docker folder). It stops all running containers while it works. With any other license, copy your Docker folder somewhere safe by hand. Either way, keep your
custom.ymland the app files incompose/HOSTNAME/. - Go to Prerequisites > Environment.
- If Deployrr says the Docker Environment is already set up, read the warning. Choose Yes to continue.
- If Deployrr asks what to do with your existing Docker folder, you see three options:
- Reuse: keeps
appdata,.envandsecrets. Everything else in the folder is removed, including the app files incompose/HOSTNAME/. The menu says it keepscustom.yml, but yourcustom.ymlis then replaced with the starter one. Reuse needs a Backups folder that is set under Prerequisites > Backups Folder and exists on disk. Without it, Deployrr says “Cannot preserve data” and stops. - Recreate: deletes everything in the Docker folder. Deployrr copies the folder to your Backups folder first, if one is set. With no Backups folder, nothing is kept.
- Exit: makes no changes.
- Reuse: keeps
- Wait for the “Creating starter compose files…” step. You should see “Base compose file created” with the file name, then “Compose file placeholders verified”.
- Copy your own services back into the new
custom.ymlfrom your backup. Install your apps again, so Deployrr adds them back to the stack.
Find a YAML error
Section titled “Find a YAML error”Use this when YAML Yoda reports a problem, or Docker names a line. YAML Yoda only checks syntax. It does not check the four placeholder lines.
-
Run Tools > Diagnostics > YAML Yoda. If it finds an error, it shows the file and the message. See Deployrr shows “Unhealthy - Issues detected” for the other Diagnostics checks.
-
You can run the same check yourself in your Docker folder. Replace
FILEwith the path of the file you want to test:Terminal window sudo docker compose -f FILE configIf the file is broken, Docker prints an error with a line number, such as
yaml: line 12: found character that cannot start any token. If the file is fine, Docker prints the whole file. -
Open the file at that line. Look for these mistakes:
- A tab instead of spaces. YAML only allows spaces.
- A line indented by a different amount than its neighbors.
- A missing colon, or a missing space after a colon.
- A line you pasted in from another file and not lined up.
-
Fix the line, save the file, and run the check again until it passes.
Files you edit by hand, such as custom.yml, are the most likely source. See Use custom.yml and Second instances of apps for how those files are meant to look.
If it still fails
Section titled “If it still fails”Generate a log and share it when you ask for help:
- Open Settings.
- Choose Logs (Generate Sanitized Deployrr Log) and press
Yto continue. - Note the log path Deployrr shows at the end. The log is saved in the folder you started Deployrr from. Read the log yourself before you share it.
- Share the log on Discord with the exact error message.
Check it worked
Section titled “Check it worked”- The step that failed now finishes. For Prerequisites > Environment, you see “Compose file placeholders verified” and “Docker Environment setup complete”.
- Selecting Tools > Diagnostics > YAML Yoda shows “All good!”. This only proves there are no syntax errors and no missing included files.

