harthelm.yml errors
Every validation error of harthelm.yml with its code, the blockers that stop a Sync and the warnings it shows.
Last updated 2026-10-19
Harthelm checks harthelm.yml when the console's editor shows it, at every plan and Sync, at the start of prepare and
test, and when you run hart validate. Each problem names its place in the file (a JSON
Pointer such as /services/web/ports/0, plus line and column) and has a code. The console underlines the place;
hart prints line:column pointer: message; the API answers with problem
invalid-config and one entry per problem in errors[].
Check a file before you push it:
hart validate harthelm.ymlCodes are stable within harthelm/v1; new ones may be added. The messages are for people and may change. At most 100
problems are listed at a time.
Validation errors
Every one of these makes the file invalid: nothing is synced until you fix it.
| Code | When it fires | Example message | Fix |
|---|---|---|---|
syntax | The file is not YAML, is empty, holds more than one document, is not a mapping, is larger than 1 MiB, nests deeper than 100 levels, expands aliases to more than 100 000 values, or uses merge keys (<<). | the file is empty; it needs at least schema: harthelm/v1 | Write one YAML mapping. Instead of <<, repeat the keys, or keep shared parts in an x- key and use plain aliases. |
version | schema is missing or is not harthelm/v1. | schema must be harthelm/v1, not "v2"; this Harthelm reads only harthelm/v1 | Start the file with schema: harthelm/v1. |
schema | A value has the wrong type, is not one of the allowed values, does not match its pattern or range, or a required key is missing. Service and variable names that do not fit their rules are reported here too. | "Web" is not a service name: lower-case letters, digits and dashes, starting with a letter, at most 32 characters | Check the key in the harthelm.yml reference. |
unknown-key | A key the schema does not know and that does not start with x-. | Fix the spelling, or start the key with x- to keep it as a note. | |
reserved-name | A service named ide, or an environment variable starting with HART_. | ide is reserved: it is the name of the workspace's IDE pod | Choose another name. HART_ variables are Harthelm's; see Workspace environment. |
duplicate-port | A service lists the same port twice. | port 3000 is listed twice in service web | Remove one. |
duplicate-public-port | Two services make the same port public, or a public port is 3000, the dev URL's entry port. | port 3000 cannot be public: the dev domain's host … carries the routes of all services | Use another port; route paths to the dev URL instead of making 3000 public. |
duplicate-route | Two routes of the landscape have the same path. | the path /api is already routed to service api | Give each route its own path. |
reserved-port | A service uses port 7777, which the workspace agent listens on in every pod. | port 7777 is reserved | Use another port. |
health-port | health.port names a port the service does not declare. | health checks port 8080, but service web … | Declare the port, or check another one. |
unknown-plan | plan is not a service plan of the installation, or the service names none and the installation's default plan is missing. | small2 is not a service plan of this installation | Use one of the plans in Limits › Plans. |
replicas | replicas is above maxReplicas, or either is above the plan's maximum. | replicas 5 is above the maximum of plan small (3) | Lower the number, or use a larger plan. |
mount | A mount's from leaves /data/app, its to is a path the pod reserves (/data, /nix, /run/harthelm, /home/harthelm, /etc/harthelm), or two mounts share a target. | ../secrets leaves /data/app; mounts can only use files of the workspace | Mount files of the workspace to free paths. See Mounts. |
template | A ${{ }} expression does not parse or is somewhere templates are not allowed; services.<name>.* outside env values; secrets.K in a managed service's config; a managed secret that is not exactly one ${{ secrets.K }}; a forward target that does not resolve to an http:// or https:// URL. | templates work only in env values, managed config and secrets, and forward targets | Move the template to an allowed place. Write $${{ for a literal ${{. |
unknown-reference | A template names a root other than workspace, team, env, secrets and services, an unknown field, or services.<name> for no managed service of the file. | unknown reference services.db.host: this file has no managed service db | Use one of the expressions of the env reference. |
unset-env | ${{ env.K }} names a workspace variable that is not set. The console offers Set K. | the workspace has no env var NODE_ENV; set it in the Env vars panel | Set the variable with Environment variables or hart env. |
unknown-need | needs names no service of the file. | service web needs api, but this file has no service api | Fix the name. |
needs-cycle | needs lead back to the service itself. | needs go in a circle: web → api → web | Remove one of the needs. See Services that need each other. |
size | A managed service's resource is not a whole MiB, or is too large. | storage: 1.5Gi is not a whole MiB | Write sizes such as 2048MiB, 2048Mi or 2Gi. |
managed-config | A managed service's plan, resources, config or secrets do not fit its provider. A size unit on a resource that counts something else (CPU) is reported here too. | Check the provider's options on the Managed services page. | |
update-constraint | A change to an existing managed service that its provider forbids: a value that cannot change, can only grow or only take an upgrade, another provider or provider version, or more storage than the volume can hold when your installation's storage class cannot grow volumes. | service db runs on version 17 of postgres and keeps it; another version needs a service with a new name, which starts empty | Keep the value, or add a service with a new name (it starts empty). |
too-many-errors | More than 100 problems were found; the rest are left out. | 12 more problems are not listed; fix these first | Fix the listed ones and check again. |
unset-env, managed-config and update-constraint are found when Harthelm plans the Sync, because they need the
workspace's variables, the installation's providers and the existing services; hart validate does not report them.
It checks plan and replicas against the installation's plans when it has an API and a key, and skips that with
--offline.
Sync blockers
A blocker does not make the file invalid, but the Sync cannot run until it is gone. The console lists blockers under
"The landscape cannot be synced yet:"; the API answers landscape-blocked
with one entry per blocker.
| Code | When | Fix |
|---|---|---|
unsupported-service-type | The service's type is one this installation cannot run. | Use steps, container, managed or forward. |
quota-exceeded | The landscape does not fit the team's quota; the message says which resource. | Use smaller plans or fewer replicas, stop other workspaces, or ask for a larger quota. |
disk-quota-exceeded | The workspace's files use more than its volume ("The workspace uses … of its … volume. Delete files before the Sync."). | Delete files in the workspace. |
run-as-not-allowed | A service sets runAsUser, and the team may not. | Remove runAsUser, or ask a cluster admin to allow it for the team. |
image-unavailable | A container image cannot be used. The reason in parentheses is one of invalid-reference, not-found, denied (add the registry's credentials in the team settings), unreachable, no-matching-platform and not-allowed (the installation does not allow images from that registry). It also fires for an image with neither ENTRYPOINT nor CMD. | Fix the image reference, add credentials (see Use private registries), or set command. |
forward-target-refused | The installation's network rules refuse the forward target by its address alone. | Use another target. |
provider-unavailable | A managed service's provider or version cannot be used: unknown, disabled, not offered to the team, or the cluster cannot run it. | Use another provider or version, or ask your administrator. |
managed-service-name-in-use | A managed service an earlier Sync removed is still being deleted, or a service changes its type to or from managed. | Sync once without the service, then add the new one. |
managed-secret-invalid | A secret value of a managed service is not accepted by its provider. | Set a new value for the vault key the message names, then plan again. |
Secrets without a value are not blockers: the console asks for them before the Sync, and the API answers
secrets-missing.
Sync warnings
Warnings do not stop the Sync. Read them before you confirm.
| Code | What it tells you |
|---|---|
image-user-ignored | The image names a USER (root or a fixed user ID) that the service will not run as. It runs as the workspace's user (the volume's user ID, group 0) instead. |
image-unpinned | The image is a tag. The Sync pins today's digest; a later Sync picks up where the tag has moved. |
forward-target-external | A forward target leaves the cluster; requests reach it with the router's address. |
managed-service-removed | A managed service of the landscape is no longer in the file: the Sync deletes it and its data. If you renamed it, the new service starts empty and the last nightly dump keeps the old data. |