Error codes and fixes

How to read an error

Every error has three parts:

Part	Example	Where you see it
Error code (reason_code)	HEALTHCHECK_FAILED	The CLI’s --json output, and the text copied with “Sao chép diagnostic ID” (copy diagnostic ID)
Vietnamese sentence (summary_vi)	“Bản mới không qua readiness trong thời gian khởi động. Bản cũ vẫn phục vụ.”	Console and CLI
Next step (next_action)	fix_input	The line under the error in the console, the bước tiếp: (next step) line in the CLI

next_action	Console shows	CLI shows	Meaning
fix_input	“Kiểm tra và sửa thông tin.”	sửa đầu vào rồi chạy lại	Fix your code, config or input and try again
rerun_plan	“Tạo plan mới để kiểm tra lại.”	chạy lại plan	The old plan no longer holds; create a new one
owner_review	“Cần owner hoặc admin xem và quyết định.”	chủ workspace cần xem và duyệt	An Owner or Admin needs to approve or upgrade
wait	“Đang xử lý, vui lòng chờ.”	chờ rồi kiểm tra lại	Wait a moment and try again
contact_operator	“Cần đội Embra kiểm tra trước khi tiếp tục.”	liên hệ người vận hành	The Embra team needs to look. See When to contact us
none		không cần làm gì thêm	No error

The “Nội dung từ app — không do Embra viết” block (content from your app, not written by Embra) under an error is text taken from your app or repo: the tail of the build log, your app’s response to the health check, a Postgres error, the DNS records Embra read. The real cause is often here.

How to find a code

• Ctrl+F (Cmd+F on a Mac), then type the error code, for example BUILD_FAILED.
• Console only shows the Vietnamese sentence? Type its first few words: each entry below lists the sentences you usually see.
• Each code has its own URL: docs.embra.cloud/en/loi/#<code in lowercase>, for example /en/loi/#healthcheck_failed.

When to contact us

Email hello@embra.cloud with:

1. The operation ID (operation_id): the operation: line in the CLI, or the text copied with “Sao chép diagnostic ID” in the console.
2. The workspace, project and environment (for example shop/production).
3. The time of the error, saying whether it is Vietnam time or UTC.
4. The error code and sentence, if you have them.

When an error needs the Embra team (contact_operator), the console has a “Liên hệ hỗ trợ” (contact support) button that opens an email draft with the operation ID and error code filled in. The draft only holds identifiers, never secrets or your data.

Build and deploy

BUILD_FAILED

HTTP	Auto retry	next_action	Exit code	Next step
200	No	fix_input	10	Fix as described here, then retry

Embra could not build an image from your code. The running app is not affected.

If the sentence starts with embra.toml:, see REPO_CONFIG_INVALID. Other sentences:

Error sentence	Meaning
buildctl lỗi: exit … or build trong VM không thành công.	The build command (Dockerfile or Railpack) failed. The cause is in the build log
railpack prepare lỗi: exit …	Railpack’s repo analysis failed. The reason is in the build log
git fetch lỗi: …, git checkout lỗi: …	Embra could not fetch the commit from GitHub
không thấy Dockerfile.	embra.toml sets builder = "dockerfile" but there is no file at that path
root không tồn tại., root không phải thư mục., root trỏ ra ngoài repo.	root in embra.toml, or the Root directory, is wrong
Image build ra vượt giới hạn dung lượng của gói.	The image is larger than your plan’s disk space
… file migration không hợp lệ., migration trùng tên., quá 100 file migration., migration … vượt … byte.	Something is wrong in the migrations folder. See Writing migrations
preview.seed không tồn tại.	The file set in [preview] seed is not in the repo
Upload của build này không còn tồn tại. Upload lại rồi build.	The upload from embra deploy has expired

How to fix it:

1. Click “Xem build logs” (view build logs) and read from the bottom up. The first error from npm, pip, go or docker is usually the cause.
2. Run the same build command on your machine. With a Dockerfile, run docker build . at the repo root (or in root).
3. Log shows egress từ chối "<host>" (egress denied): the build needs a host that is not open yet. Email that host name to hello@embra.cloud. Open hosts: How Embra builds your app.
4. Image too large: use a multi-stage Dockerfile that copies only the build output (for example dist/) into the last stage, install production dependencies only (npm ci --omit=dev), add a .dockerignore that drops node_modules, .git and test files.
5. builder = "dockerfile" without a Dockerfile: remove the builder line so Embra picks Railpack, or fix dockerfile to the right path, relative to root.
6. Commit and push again.

Sample multi-stage Dockerfile for a Node app

# Ví dụ Dockerfile nhiều stage cho app Node
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
CMD ["node", "dist/main.js"]

Data safe? Yes. A failed build deploys nothing and does not touch the database.

Retry? The same commit usually fails the same way. không khởi động được VM., VM tắt trước khi sẵn sàng. and mất kết nối với embra-buildd giữa chừng build. are on Embra’s side: click “Build lại” (rebuild) once.

Contact us when: an Embra-side error repeats after a rebuild, or the build works on your machine but fails on Embra and the log does not show why.

BUILD_TIMEOUT

HTTP	Auto retry	next_action	Exit code	Next step
200	No	fix_input	10	Fix as described here, then retry

The build ran too long and was stopped. Sentence: build vượt thời gian cho phép. The build time limit depends on your plan and is never more than 25 minutes. The running app is not affected.

Cause	Fix
Installing dependencies without a lockfile, so the whole tree is resolved again	Commit your lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock…)
Tests, lint or large downloads inside the build	Move tests and lint to CI
A Dockerfile step waits on a host that is not open until time runs out (log shows egress từ chối)	Email the host name to hello@embra.cloud
The Dockerfile copies all code before installing dependencies, so every change reinstalls	Copy the dependency manifest and install first, code after (sample below)

COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

Open “Xem build logs” to see where the build stopped, fix it and push again.

Data safe? Yes. Nothing is deployed.

Contact us when: the build stops while downloading from a host that is open, or it takes under 25 minutes on your machine but still times out on Embra.

HEALTHCHECK_FAILED

HTTP	Auto retry	next_action	Exit code	Next step
200	No	fix_input	10	Fix as described here, then retry

The new version started but did not answer the health check correctly, so Embra did not move traffic to it (or moved traffic back to the old version).

Error sentence	App right now
Bản mới không qua readiness trong thời gian khởi động. Bản cũ vẫn phục vụ.	The old version keeps running. On a first deploy, nothing is running yet
Bản mới lỗi sau khi nhận traffic, route đã được trả về bản cũ.	The new version failed during the 30-second watch; traffic is back on the old version
App không qua readiness sau khi chạy lại; app vẫn đang tạm dừng.	You turned a paused app back on but it did not come up; the app stays off
App không chạy được trên bản khôi phục (không qua readiness). …	The restore was cancelled; the old app and database keep running
Deploy đã xong nhưng app chưa trả lời kiểm tra sức khoẻ sau 2 phút. … (CLI)	embra deploy waited 2 minutes and the app is not healthy yet. Check the app log

Embra sends a GET to health_path every 2 seconds and needs 3 consecutive 2xx responses within startup_grace_seconds (60 seconds by default). Details: Health check.

Cause	Fix
The app listens on 127.0.0.1 or localhost, unreachable from outside the container	Listen on 0.0.0.0 (framework samples below)
The app listens on a port other than [deploy] port (3000 by default), such as the framework default (8000, 8080, 5173)	Read the port from the PORT env var. Embra sets PORT to [deploy] port unless you set a PORT secret yourself
health_path returns 3xx: a redirect to login, to HTTPS or to add a trailing /. Redirects do not count as passing	Add a dedicated route, for example /healthz, returning 2xx with no login and no redirect
health_path returns 4xx: the path does not exist, needs login, or the framework blocks an unknown Host header. Embra calls the container’s internal IP directly, so Host is IP:port, not your domain	As above; for Django see the middleware sample below
The app crashes on startup: missing secret, no database connection, migrations on startup (the app’s database user cannot change the schema)	Read the app log. Remove startup migrations (prisma migrate deploy, TypeORM synchronize: true…): migrations go through Embra, see Database and migrations
The app takes longer to start than startup_grace_seconds	Raise startup_grace_seconds (at most 300)

How to fix it:

1. Open “Logs” and read the app log around the failed deploy. Startup crashes show up clearly here.

2. Read the “Nội dung từ app — không do Embra viết” block: your app’s response to the last health check.

3. Fix per the table above and set the health route in embra.toml:

   [deploy]
   health_path = "/healthz"

4. Push again.

Listening on 0.0.0.0:$PORT per framework

Express:

const port = Number(process.env.PORT) || 3000;
app.get('/healthz', (req, res) => res.send('ok'));
app.listen(port, '0.0.0.0');

NestJS (src/main.ts):

await app.listen(Number(process.env.PORT) || 3000, '0.0.0.0');

Next.js (package.json):

{
  "scripts": {
    "start": "next start -H 0.0.0.0 -p ${PORT:-3000}"
  }
}

With output: 'standalone' and node server.js in a Dockerfile, also set HOSTNAME:

ENV HOSTNAME=0.0.0.0
CMD ["node", "server.js"]

Django (gunicorn, in a Dockerfile):

CMD gunicorn myproject.wsgi --bind 0.0.0.0:${PORT:-3000}

Django returns 400 when Host is not in ALLOWED_HOSTS, and may redirect to HTTPS when SECURE_SSL_REDIRECT is on. Give the health check its own middleware, placed first in MIDDLEWARE:

myproject/health.py

from django.http import HttpResponse


class HealthCheckMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        if request.path == "/healthz":
            return HttpResponse("ok")
        return self.get_response(request)

settings.py

MIDDLEWARE = [
    "myproject.health.HealthCheckMiddleware",
    # ... các middleware còn lại
]

Laravel (in a Dockerfile):

CMD php artisan serve --host=0.0.0.0 --port=${PORT:-3000}

$PORT in array form

CMD ["node", "server.js"] and start = ["node", "dist/main.js"] in embra.toml are array forms that skip the shell, so a $PORT written there is not replaced with its value. Read PORT in your code, or wrap it in a shell: CMD ["sh", "-c", "gunicorn myproject.wsgi --bind 0.0.0.0:$PORT"].

Data safe? It depends:

• The new version did not pass the health check: no real traffic reached it. But it did run its startup code with DATABASE_URL, so anything that code wrote (for example a seed on startup) stays.
• The new version failed after receiving traffic: it served real requests while being watched. Data written then stays in the database.
• In every case: if the plan had migrations, migrations that ran stay applied, and the old version is running on the new schema. Don’t edit an applied migration to “undo” it, or Embra reports MIGRATION_HISTORY_CHANGED. To change the schema back, add a new migration file.

Retry? Not without changing something: the health check will fail the same way.

Contact us when: the app listens on 0.0.0.0:$PORT and returns 2xx on health_path when run with Docker on your machine, but Embra still reports this error.

REPO_CONFIG_INVALID

HTTP	Auto retry	next_action	Exit code	Next step
400	No	fix_input	2	Fix as described here, then retry

Your embra.toml has an error. The sentence always starts with embra.toml: and names the wrong field. Found during a build, it shows as BUILD_FAILED with the same sentence.

Error sentence (examples)	How to fix it
embra.toml: field lạ deploy.prot.	Fix the field name (here, port). Embra does not ignore unknown fields
embra.toml: field deploy.port sai kiểu giá trị.	Fix the type: port = 3000, not port = "3000"
embra.toml: sai cú pháp TOML ở dòng 12.	Fix the syntax on that line (missing quote, missing ]…)
embra.toml: build.builder phải là "railpack" hoặc "dockerfile".	Fix the value, or remove the line so Embra picks one
embra.toml: deploy.startup_grace_seconds phải > 0.	Use 5 to 300 seconds
embra.toml: … phải là đường dẫn tương đối trong repo., … không được trỏ ra ngoài repo.	Path from the repo root (or from root), no leading /, no .. leaving the repo
embra.toml: build.env.EMBRA_…: tiền tố EMBRA_ dành riêng cho Embra.	Rename the variable
embra.toml: cron.<tên>.schedule: …	5-field cron, in UTC, at least 5 minutes apart
embra.toml: file vượt 65536 byte.	Shorten the file to at most 64 KiB

Compare with the embra.toml reference. Check the syntax locally, for example python3 -c "import tomllib; tomllib.load(open('embra.toml','rb'))", then commit and push again.

Data safe? Yes. Nothing is deployed.

SOURCE_NOT_CONNECTED

HTTP	Auto retry	next_action	Exit code	Next step
409	No	fix_input	10	Fix as described here, then retry

Embra cannot read this environment’s GitHub repo.

Sentences:

• Environment chưa nối với repo GitHub. …
• Environment không còn nối với repo GitHub.
• GitHub installation đã bị gỡ hoặc tạm dừng.
• Không lấy được quyền đọc repo: installation đã bị gỡ, tạm dừng hoặc mất quyền truy cập repo.
• Không đọc được nhánh đã nối: repo, nhánh hoặc installation không còn truy cập được.
• Hãy đăng nhập bằng GitHub trước khi kết nối repo.

Common causes:

• The Embra GitHub App was uninstalled or suspended on the account or organization.
• When installing the GitHub App you chose “Only select repositories” and this repo is not in it (or was just removed).
• The repo was renamed, transferred or deleted. The linked branch was renamed or deleted.
• You signed in to Embra with Google. Only people signed in with GitHub can link a repo.

How to fix it:

1. Open Cài đặt → “Source code” (settings → source code) → “Cài / cập nhật quyền GitHub App” (install / update GitHub App permissions).
2. Grant access to the repo on GitHub again.
3. Check the repo and branch names are still right. Branch renamed? Link the new one.
4. Click “Build lại” (rebuild).

See also Deploy from GitHub.

Data safe? Yes. The running app keeps running; Embra just cannot build a new version.

SECRET_REVOKED

HTTP	Auto retry	next_action	Exit code	Next step
409	No	fix_input	10	Fix as described here, then retry

A secret the deploy needs was revoked, or has no valid version left. For example: Một secret của release đã bị thu hồi sau khi plan. Đặt version mới rồi plan lại. or Secret <TÊN> chưa có version nào còn hiệu lực. …

1. Open Cài đặt → “Secrets”, enter a new value, click “Lưu secret” (save secret).
2. Click “Build lại” (rebuild) to create a new plan. Secrets reach the app on the next build.

See Secrets. Hit this while turning a paused app back on? The app stays off until you fix it.

ATTESTATION_MISMATCH

HTTP	Auto retry	next_action	Exit code	Next step
200	No	contact_operator	10	None, on purpose. Email hello@embra.cloud with the operation_id

The new container runs with a config different from what Embra asked for, so Embra did not move traffic to it. The old version keeps running. This is a safety check on Embra’s side; code changes won’t fix it. Email hello@embra.cloud with the operation ID.

IMAGE_DIGEST_REQUIRED

HTTP	Auto retry	next_action	Exit code	Next step
400	No	fix_input	10	Fix as described here, then retry

embra deploy --image needs an image pinned by digest: <image>@sha256:<64 hex characters>, not a tag like :latest.

SOURCE_ARCHIVE_INVALID

HTTP	Auto retry	next_action	Exit code	Next step
400	No	fix_input	2	Fix as described here, then retry

The source embra deploy uploaded was rejected (not a valid tar.gz, or it has a file type that is not allowed). Remove the unusual files or add them to .embraignore, and run again.

SOURCE_TOO_LARGE

HTTP	Auto retry	next_action	Exit code	Next step
422	No	fix_input	10	Fix as described here, then retry

The upload is over your plan’s limit: the source from embra deploy, or a dump file when importing data (larger than your plan’s database space). The sentence states the file size and the limit. Make the file smaller (add .embraignore, drop tables you don’t need) or upgrade.

Database and migrations

Migration sentences sometimes give the statement’s “lớp” (class). Match it to How Embra checks migrations:

Class	Group
A	Safe
B	Changes or deletes data
C	Long table lock
D	Cannot run in a transaction
E, F	Not supported (E: Embra cannot parse the statement; F: forbidden)

MIGRATION_UNSUPPORTED

HTTP	Auto retry	next_action	Exit code	Next step
422	No	fix_input	10	Remove the class E/F statement, push again

A statement in a migration file is of a kind Embra cannot run yet, so the plan is refused before the database is touched. After a successful build, the console shows “Build xong · cần sửa config” (build done, fix config) and “Không tạo được plan deploy” (could not create a deploy plan).

Sentences:

• File 0003_x.sql, câu lệnh #2 (CreateFunctionStmt) lớp E: … or … lớp F: …
• File 0003_x.sql: không đọc được SQL nên không thể chứng minh an toàn.
• File 0004_x.sql, câu lệnh #1 (IndexStmt) lớp D: … lệnh không chạy trong transaction (như CREATE INDEX CONCURRENTLY) phải ở file riêng, chỉ có đúng một câu lệnh
• SQL của migration đã thay đổi bảng nội bộ của Embra. Đã rollback; không được phép.
• Migration không hợp lệ để chạy trên production.

Cause	Fix
The file has a function, procedure, trigger, view, DO block, CREATE EXTENSION, CREATE SCHEMA, GRANT/REVOKE or COPY (common in ORM-generated migrations)	Move that logic into app code. Embra cannot run these yet
The file has BEGIN/COMMIT	Remove them. Embra wraps each file in a transaction itself
CREATE INDEX CONCURRENTLY shares a file with other statements	Move it to its own file, with only that statement
SQL for another database (MySQL, SQLite) or Postgres syntax Embra cannot parse	Rewrite it as Postgres SQL

Find the statement by its # number (counting from 1) in the file the sentence names; the original statement is in the “Nội dung từ app — không do Embra viết” block. The file never ran, so edit it directly, then commit and push again.

Data safe? Yes. Embra refuses at the planning step. Only SQL của migration đã thay đổi bảng nội bộ của Embra. happens while running, and Embra rolled that statement back.

MIGRATION_REHEARSAL_FAILED

HTTP	Auto retry	next_action	Exit code	Next step
200	No	fix_input	10	Fix the SQL, check with embra plan, then push

A migration failed:

Error sentence	Where it failed
Diễn tập migration thất bại trên bản sao dữ liệu; chưa đụng production. …	On a copy of your data. Production was not touched
Migration lỗi trên production dù đã diễn tập thành công: production khác bản sao. Câu lệnh lỗi đã rollback.	On production. The failing statement was rolled back

The Postgres error (for example column "status" of relation "orders" contains null values) is in the “Nội dung từ app — không do Embra viết” block, with the failing file and statement.

Common causes:

• Adding a NOT NULL column without a DEFAULT to a table that has rows.
• Creating a UNIQUE constraint or foreign key that existing data violates (duplicates, references to missing rows).
• Changing a column type when old data cannot be converted (for example text to number).
• Referencing a table or column that does not exist yet, because of file order.
• A migration that works on an empty local database but fails with real data.

How to fix it: change the SQL so it works with the existing data. For example, add a required column in three steps:

ALTER TABLE orders ADD COLUMN status text;
UPDATE orders SET status = 'paid' WHERE status IS NULL;
ALTER TABLE orders ALTER COLUMN status SET NOT NULL;

Or shorter: ALTER TABLE orders ADD COLUMN status text NOT NULL DEFAULT 'paid';

The failing file was not applied, so edit it directly. Don’t edit files applied by earlier deploys. Commit and push again; Embra rehearses again before running.

Data safe? Failed in rehearsal: production was not touched. Failed on production: the failing statement was rolled back and the old code keeps running. Each file runs in its own transaction, so with several files the ones before the failing file may already be applied; Embra records them and only runs the rest next time.

Contact us when: it failed on production and you can’t find how production differs from the copy.

MIGRATION_LOCK_TIMEOUT

HTTP	Auto retry	next_action	Exit code	Next step
200	No	rerun_plan	10	New plan: “Build lại” (rebuild) or embra build

The migration needs a table lock, but another query holds it too long. Embra retries many times with short timeouts so your app does not hang, then stops.

Sentence: Không lấy được khoá bảng trong thời gian cho phép (có truy vấn dài đang giữ). Chưa áp file nào còn dở; code cũ vẫn phục vụ.

Causes: long-open transactions or connections “idle in transaction” (opened and never committed); a long report or export query on that table; a cron job or worker processing that table in bulk.

How to fix it:

1. Stop the long query: end the report job, or fix the code that opens a transaction without closing it.
2. Pick a time with little traffic.
3. Create a new plan: click “Build lại” (rebuild), or run embra build.

Data safe? Yes. The file waiting for the lock did not run, no file is half-applied, the old code keeps running. With several files, earlier ones may already be applied; the next plan only runs the rest.

Retry? Yes, once the long query is done.

MIGRATION_DATA_LOSS

HTTP	Auto retry	next_action	Exit code	Next step
202	No	owner_review	20	Approve on the web, type CONFIRM_MIGRATION

Not an error: the plan is waiting for approval, and the rehearsal shows the migration will delete or overwrite data (for example DROP COLUMN, DROP TABLE, DELETE). Applies to staging too.

1. Click “Xem và duyệt” (review and approve) and read what data will be lost: tables, columns, estimated rows.
2. Need that data? Take it out first: Cài đặt → “Dữ liệu” → “Export dữ liệu” (settings → data → export data), or copy it to another table in a separate migration.
3. Agree: type the environment name and CONFIRM_MIGRATION, click “Duyệt và deploy” (approve and deploy).
4. Don’t agree: click “Từ chối” (reject), then fix the migration.

Only an Owner or Admin can approve. See Approving production.

Data safe? Nothing runs until you approve. Once applied, you cannot restore to a point before the migration yourself (see MIGRATION_AFTER_RESTORE_POINT), so be sure before approving.

MIGRATION_HISTORY_CHANGED

HTTP	Auto retry	next_action	Exit code	Next step
409	No	fix_input	10	git checkout <commit> -- migrations/<file>

The migration files in the repo do not match what already ran on the environment.

Error sentence	How to fix it
File 0002_x.sql đã áp lên environment nhưng nội dung đã đổi. …	Put the file back to the content that ran (for example git checkout <commit cũ> -- migrations/0002_x.sql). To change more, add a new file
File đã áp lên environment bị thiếu trong plan: … Giữ nguyên mọi file đã áp.	Bring back deleted or renamed files under their old names
File mới 0003_x.sql nằm trước file đã áp 0005_y.sql. Đặt số lớn hơn 0005_y.sql.	Rename the new file with a number above the last applied file

Common causes:

• Editing a migration that already ran to “fix” it.
• Merging, deleting or renaming old migrations to tidy up.
• With Prisma, re-running the copy script after deleting or editing old Prisma migrations, which shifts the numbering. See Writing migrations.
• Two branches both add a migration and the one merged later has the smaller number.

Data safe? Yes. Embra refuses at the planning step; nothing ran.

SCHEMA_DRIFT

HTTP	Auto retry	next_action	Exit code	Next step
409	No	rerun_plan	10	New plan: “Build lại” (rebuild) or embra build

The production schema changed since the rehearsal, so the rehearsal result no longer holds and the plan was cancelled. No file was applied. Create a new plan (click “Build lại” (rebuild), or embra build) so Embra rehearses again.

POOL_IOPS_BUDGET_EXCEEDED

HTTP	Auto retry	next_action	Exit code	Next step
422	No	contact_operator	10	None, on purpose. Email hello@embra.cloud with the operation_id

The server has used up its disk-write budget, so Postgres could not be created. This is a limit on Embra’s side. Email hello@embra.cloud with the operation ID.

Domains

DOMAIN_NOT_VERIFIED

HTTP	Auto retry	next_action	Exit code	Next step
200	No	fix_input	10	Fix as described here, then retry

Embra could not verify your domain yet. It needs both the right TXT record and the domain pointing at Embra. The sentence names exactly what is missing, for example:

Chưa xác minh được www.shop.vn: thiếu bản ghi TXT _embra-challenge.www.shop.vn = embra-verify=…; hostname chưa trỏ về Embra (cần CNAME tới …, hoặc A/AAAA tới IP của edge).

The DNS values Embra read are in the “Nội dung từ app — không do Embra viết” block.

Cause	Fix
DNS has not propagated yet (usually 5–30 minutes)	Wait a few minutes
Cloudflare proxy on (orange cloud), so Embra only sees Cloudflare IPs	Switch the records to DNS only (grey cloud)
TXT name with the domain appended twice: many providers add the domain, so typing the full name gives _embra-challenge.www.shop.vn.shop.vn	If the “Name” field appends the domain, type only _embra-challenge.www (or _embra-challenge for a root name)
A CNAME on the root name (shop.vn)	The root name uses an A record to the IP Embra shows
An old A or CNAME record still points elsewhere	Delete old records with the same name

The records Embra asks for are under Cài đặt → “Domain”. When done, click “Kiểm tra” (check); each domain can be checked at most once every 30 seconds. See Custom domains.

Data safe? Yes. The app keeps running at its .onembra.com address.

DOMAIN_TAKEN

HTTP	Auto retry	next_action	Exit code	Next step
409	No	fix_input	10	Fix as described here, then retry

The domain is already verified on another environment on Embra; a domain can only be attached to one app. Sentence: Hostname này đã được xác minh ở một environment khác.

Causes: the domain is still attached to an old app, to staging, or to another workspace of yours (for example a trial workspace); or someone else verified it earlier.

How to fix it:

1. Domain on another app of yours: open Cài đặt → “Domain” in that app, click “Xoá” (remove).
2. Go back to the new app and add the domain again.

Not attached anywhere you know of? Email hello@embra.cloud with the domain name. Embra does not reveal which workspace holds the domain.

Data safe? Yes. The app keeps running at .onembra.com. Retrying does not help until the domain is removed from the other place.

Account and plans

QUOTA_EXCEEDED

HTTP	Auto retry	next_action	Exit code	Next step
422	No	owner_review	10	Owner or Admin reviews on the web

Over a limit of your plan or of the server. The sentence says which limit, usually with numbers.

Error sentence (examples)	What to do
Gói dùng thử chỉ có một environment …, Gói dùng thử cho tối đa …	Upgrade, or delete what you don’t use. See The trial
Hồ tài nguyên app của gói là … không đủ cho release này …, Tổng cỡ app sẽ là … vượt hồ tài nguyên …	Shrink other apps in Cài đặt → “Tài nguyên” (settings → resources), or upgrade
Gói … có tối đa … database cho app production …	Delete unused databases, or upgrade. Staging and preview don’t count
Workspace đã dùng hết số domain riêng của gói …	Remove unused domains, or upgrade
Gói … không có staging. …, Mỗi project có tối đa một staging. …	Upgrade, or delete the old staging
Gói … cho tối đa … preview environment …	Close some PRs, or wait for old previews to be removed
Gói … không có object storage., Environment đã có bucket; …	See Storing files
After a successful build, the console shows “Không tạo được plan deploy” because of workers or cron	Remove some [processes.*] or [cron.*] from embra.toml to fit the plan, or upgrade, then push again
Gói hiện tại giữ … ngày lịch sử log …, … ngày lịch sử metrics …	Pick a more recent time range
Workspace đang mở … luồng log, tối đa cho phép. …	Close some tabs showing logs
Verify quá dày. …	Each domain can be checked once every 30 seconds, and each workspace has an hourly limit. Wait, then click “Kiểm tra” (check) again
Node hết dải mạng …, Hết dải mạng để cấp cho preview mới., Không đủ chỗ chạy hai database song song để khôi phục …	A server limit, not a plan limit. Email hello@embra.cloud
Máy chủ chưa đủ ngân sách ghi đĩa để chạy thêm database cũ nên không rollback được. …	The current app and database keep running normally. Email hello@embra.cloud if you need the rollback urgently

Upgrading: Owner only, in a browser, from the account menu → “Thanh toán” (billing). See Account, trial and payment.

Data safe? Yes. Embra refuses before doing anything; nothing changes.

TRIAL_EXPIRED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	owner_review	10	Owner or Admin reviews on the web

The 7-day trial has ended. The console shows “Dùng thử đã hết hạn” (trial expired).

Sentence: Gói dùng thử đã hết hạn: mọi request tới workspace này bị từ chối và dữ liệu sắp bị xoá. Dữ liệu cần lấy phải export trước hạn.

• Every action is refused, including viewing. Only the Owner can still see payment details and switch to another workspace.
• After that the whole workspace is deleted: apps, databases and backups.
• Chose a plan before the trial ended: Embra keeps the workspace 72 more hours waiting for the transfer. The screen shows the transfer code, QR, amount and deletion time. Pay before then and the workspace reopens. Paid less than the amount? The workspace is not deleted but stays locked: email hello@embra.cloud.

What to do:

1. No plan chosen but need to keep the app or data? Email hello@embra.cloud right away with the workspace name. This screen has a “Liên hệ hỗ trợ” (contact support) button.
2. Other trial workspaces: choose a plan and pay before the trial ends. See The trial.

Retry? No. Every request to this workspace is refused.

SIGNUP_CLOSED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	contact_operator	10	None, on purpose. Email hello@embra.cloud with the operation_id

Embra is not letting this account in yet. The console shows “Chưa vào được Embra” (cannot get into Embra yet).

Error sentence	What to do
Email Google này chưa được mời vào workspace nào. …	Google sign-in is only for invited people. Ask an Owner to invite that exact email, or sign in with GitHub
Tài khoản GitHub phải được tạo ít nhất … ngày trước mới đăng ký dùng thử được.	Email your GitHub username to hello@embra.cloud to have that account let in
Đợt dùng thử hôm nay đã đầy. …	Try again tomorrow, or email hello@embra.cloud for an invitation
Đăng ký dùng thử đang đóng. …	Email hello@embra.cloud for an invitation

See Signing in.

Retry? Only when today’s trial slots are full: try again tomorrow. The other cases need an invitation or an email to the Embra team first. No workspace was created, so no data is affected.

WORKSPACE_DELETED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	contact_operator	10	None, on purpose. Email hello@embra.cloud with the operation_id

The account still exists but every workspace it had is deleted: deleted by you, or a trial that ended and was cleaned up after the hold period. The console shows “Workspace của bạn đã bị xoá” (your workspace was deleted).

The trial is once per account. Email hello@embra.cloud to open a new workspace on a paid plan. Data of a deleted workspace cannot be restored.

Since the Embra release with T254, signing in again opens a workspace with no plan instead (see PLAN_REQUIRED); this code is only returned by older releases.

Retry? No. Signing in again gives the same error until there is a new workspace.

PLAN_REQUIRED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	owner_review	10	Owner or Admin reviews on the web

The workspace has no plan (“Chưa có gói”, no plan). Embra opens one when you sign in again after every earlier workspace was deleted: the trial is once per account. A workspace with no plan cannot create projects, environments or forks.

The owner opens Thanh toán (Billing), chooses a plan and pays by bank transfer with the VietQR code. Once the money arrives the plan is active and projects can be created.

Retry? No. Choose and pay for a plan first, then try again.

WORKSPACE_SUSPENDED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	contact_operator	30	None, on purpose. Email hello@embra.cloud with the operation_id

The Embra team suspended the workspace, usually after an abuse report.

Sentence: Workspace đang bị tạm ngưng: chỉ đọc được, mọi thao tác ghi bị từ chối. Dữ liệu được giữ nguyên. Liên hệ abuse@embra.cloud để khiếu nại.

• Apps stop receiving traffic. Data is kept as is.
• You can still view things, but cannot deploy, change config or change plans.

What to do: email abuse@embra.cloud with the workspace name, explaining what the app does and why you think the suspension is a mistake.

Retry? No. Every write is refused until the Embra team lifts the suspension.

ENVIRONMENT_SUSPENDED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	contact_operator	30	None, on purpose. Email hello@embra.cloud with the operation_id

Like WORKSPACE_SUSPENDED, but for one environment. Its app stops receiving traffic; data is kept. Appeal through abuse@embra.cloud.

Permissions and approval

APPROVAL_REQUIRED

HTTP	Auto retry	next_action	Exit code	Next step
202	No	owner_review	20	Owner or Admin reviews on the web

Not an error: the plan is waiting for an Owner or Admin to approve. Production always needs approval, even without migrations. Staging and previews need approval when a migration changes or deletes data.

1. Open the overview page as an Owner or Admin → “Xem và duyệt” (review and approve).
2. Review the code, config and data changes.
3. Type the environment name → “Duyệt và deploy” (approve and deploy).

Developers and AI agents can create plans but cannot approve them. A pending plan expires after 24 hours. Approving needs a real person who signed in recently: see Actions that need a real person.

Data safe? Yes. Nothing runs until it is approved. The running app keeps running.

APPROVAL_EXPIRED

HTTP	Auto retry	next_action	Exit code	Next step
409	No	rerun_plan	10	New plan: “Build lại” (rebuild) or embra build

Something waiting for approval went past its deadline and was cancelled. Nothing was applied.

Error sentence	What to do
Plan đã hết hạn duyệt nên bị huỷ. …	Create a new plan: click “Build lại” (rebuild), or embra build
Bằng chứng diễn tập migration đã hết hạn nên plan bị huỷ. …	Create a new plan. A rehearsal result is only valid for 24 hours
Lần nhập dữ liệu đã hết hạn duyệt nên bị huỷ; database không đổi và file đã bị xoá. …	Upload the file again to import it
Restore đã hết hạn duyệt nên bị huỷ …	Create the restore again from “Khôi phục dữ liệu…” (restore data)
Request fork đã quá hạn duyệt …	Request the fork again

Data safe? Yes. The cancelled item never touched the running app or database. The old plan cannot be approved again: create a new one.

GENERATION_CONFLICT

HTTP	Auto retry	next_action	Exit code	Next step
409	No	rerun_plan	10	New plan: “Build lại” (rebuild) or embra build

The environment changed since the plan was made (for example another deploy or rollback finished), so the old plan was cancelled to avoid approving the wrong thing. Create a new plan.

BINDING_MISMATCH

HTTP	Auto retry	next_action	Exit code	Next step
409	No	rerun_plan	10	New plan: “Build lại” (rebuild) or embra build

You approved a different plan version from the one waiting (usually a stale page). Reload, review the plan and approve again.

FORBIDDEN_SCOPE

HTTP	Auto retry	next_action	Exit code	Next step
403	No	owner_review	10	Owner or Admin reviews on the web

Your role or token does not allow this. Ask an Owner or Admin, or get a higher role. See Members and roles.

HUMAN_REQUIRED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	fix_input	10	Fix as described here, then retry

This needs a real person, and you are using a machine token (CI, agent). Do it in the browser, or run embra login and try again. See Actions that need a real person.

REAUTH_REQUIRED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	fix_input	10	Fix as described here, then retry

Your sign-in is more than 12 hours old, and this action needs a fresh one. Console: click “Đăng nhập lại bằng GitHub” (sign in again with GitHub) or “Đăng nhập lại bằng Google” right under the error. CLI: run embra login again.

LAST_OWNER

HTTP	Auto retry	next_action	Exit code	Next step
409	No	fix_input	10	Fix as described here, then retry

This change would leave the workspace (or agency account) without an owner. Make someone else an owner first, then try again.

UNAUTHENTICATED

HTTP	Auto retry	next_action	Exit code	Next step
401	No	fix_input	1	embra login or a new token

The token is missing, wrong or expired. Sign in to the console again, run embra login, or use a valid token.

CSRF_FAILED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	fix_input	1	Fix as described here, then retry

The browser sent a request without a valid protection token, usually because the tab was open too long or opened from another site. Reload and try again.

DEVICE_ACCESS_DENIED

HTTP	Auto retry	next_action	Exit code	Next step
403	No	fix_input	1	Fix as described here, then retry

You clicked deny when approving the CLI sign-in. Run embra login again if it is your machine.

DEVICE_CODE_EXPIRED

HTTP	Auto retry	next_action	Exit code	Next step
400	No	fix_input	1	Fix as described here, then retry

The CLI sign-in code expired before you approved it in the browser. Run embra login again for a new code.

Rollback and restore

ROLLBACK_INCOMPATIBLE

HTTP	Auto retry	next_action	Exit code	Next step
409	No	owner_review	10	Fix forward with a new commit

You cannot roll back to the chosen version because migrations ran after it. A rollback only brings back code, not the schema: old code may not work on the new schema.

Sentences:

• Đã có N file migration áp lên environment sau release …. Rollback chỉ trả code, không tua dữ liệu: …
• Đã có N migration áp lên database hiện tại sau lúc chuyển; database cũ không có chúng nên không rollback được.

The list of migrations is in the “Nội dung từ app — không do Embra viết” block.

What to do:

1. Fix forward with a new commit that works with the current schema, and deploy as usual.
2. Really need the old schema? Write a new migration that changes it back.
3. Need the data from before that migration? Email hello@embra.cloud with the operation ID.

Data safe? Yes. Embra refuses before doing anything.

ROLLBACK_DB_GONE

HTTP	Auto retry	next_action	Exit code	Next step
409	No	owner_review	10	Owner or Admin reviews on the web

The rollback target uses an old database (from before a restore), but that database was deleted when its retention ended. The old data only exists in an export you took earlier. See Backups and restore.

RESTORE_POINT_UNAVAILABLE

HTTP	Auto retry	next_action	Exit code	Next step
422	No	fix_input	10	embra db restore-points

The restore point you chose cannot be used: no usable backup yet, or the point is outside the restorable range. The sentence gives the valid range. Open “Xem mốc khôi phục” (view restore points) and pick a point inside it.

MIGRATION_AFTER_RESTORE_POINT

HTTP	Auto retry	next_action	Exit code	Next step
409	No	owner_review	10	Pick a point after the migration

A migration ran after the point you chose. Restoring there would remove table structure the current app needs, so Embra blocks it. The running database and app are not touched. Pick a point after the migration the sentence names. Need data from before it? Email hello@embra.cloud.

RESTORE_SHORT

HTTP	Auto retry	next_action	Exit code	Next step
200	No	contact_operator	10	None, on purpose. Email hello@embra.cloud with the operation_id

The backup is missing data (WAL) before the chosen point, so the restore cannot reach that exact point. Production was not touched. Email hello@embra.cloud with the operation ID and the point you chose.

BACKUP_WAL_GAP

HTTP	Auto retry	next_action	Exit code	Next step
200	No	contact_operator	10	None, on purpose. Email hello@embra.cloud with the operation_id

The last automatic test restore found a gap in the backup. The console shows “Lần restore thử gần nhất thiếu dữ liệu — vùng khôi phục cần kiểm tra lại.” (the last test restore was missing data; the restorable range needs checking). The running app and database are not affected, but don’t rely on the restorable range until the Embra team checks it. Email hello@embra.cloud.

BACKUP_DATA_CORRUPT

HTTP	Auto retry	next_action	Exit code	Next step
200	No	contact_operator	10	None, on purpose. Email hello@embra.cloud with the operation_id

The automatic restore check rebuilt the database, but pg_amcheck, which reads every page and index, found corrupt data pages on the running database itself, not in the backup. The usual cause is a disk or memory fault below Postgres, rarely the app.

• The app keeps running, but a read that hits a damaged page can fail or return wrong data.
• Don’t restore over it and don’t run bulk fixes: a backup taken after the damage carries the damaged pages too.
• Email hello@embra.cloud with the operation_id, workspace and environment. The Embra team finds the affected tables and the last clean restore point.

When Embra stops to check

The three codes below share one rule: when Embra is not sure a step finished, it stops on purpose instead of retrying. Retrying something with an unknown outcome, such as running a migration twice or switching databases without knowing their state, can damage data. The Embra team checks the real state before reopening the environment.

RECOVERY_REQUIRED

HTTP	Auto retry	next_action	Exit code	Next step
200	No	contact_operator	30	None, on purpose. Email hello@embra.cloud with the operation_id

An operation on the environment (deploy, rollback, restore, app on/off…) ended without Embra knowing the outcome, for example because the connection to the server dropped midway. The console shows “Cần đội Embra hỗ trợ” (needs Embra team support), and the overview shows “Đội Embra cần kiểm tra trước khi bạn deploy tiếp” (the Embra team needs to check before you deploy again).

State right now:

• Embra keeps traffic as it was at the incident. Depending on timing, the app may be running normally, running the new version, or stopped (for example during a switch to a restored database).
• The environment is blocked: deploys, builds on push, rollback, restore, app on/off, domain changes and data imports are refused with ENVIRONMENT_BLOCKED.
• Cron jobs don’t run. Scheduled backups are paused.

Do NOT:

• Delete the environment. Still allowed, but it also deletes the database and backups the Embra team needs to check and recover.
• Run SQL yourself to “fix” the schema or data: it makes checking harder.
• Keep pushing or revoke secrets to “unblock” it: no effect.

Do:

1. Click “Liên hệ hỗ trợ” (contact support) in the console, or email hello@embra.cloud with the operation ID, workspace, environment and time.
2. Note what you did just before the error appeared.
3. If the app is failing for your users, say so in the email so the team can prioritize.

MIGRATION_UNKNOWN

HTTP	Auto retry	next_action	Exit code	Next step
200	No	contact_operator	30	None, on purpose. Email hello@embra.cloud with the operation_id

Embra lost contact while running a migration on production, so it does not know whether the migration was applied. The console shows “Cần xác minh dữ liệu” (data needs verifying).

State right now:

• The old code keeps running. The new app has not started, because Embra only starts it after migrations finish.
• The schema may be old or new. Each migration file runs in its own transaction, so a file is either fully applied or not at all (except a CREATE INDEX CONCURRENTLY file, which does not run in a transaction).
• Embra took a database snapshot right before running the migration.
• The environment is blocked as with RECOVERY_REQUIRED.

Do NOT:

• Delete the environment or the database.
• Edit, rename or delete the pending migration files, or add a new migration to “run it again”.
• Re-run the migration statements by hand.

Do: email hello@embra.cloud with the operation ID, workspace, environment and time. The Embra team checks the real schema, records the right outcome and reopens the environment.

ENVIRONMENT_BLOCKED

HTTP	Auto retry	next_action	Exit code	Next step
409	No	contact_operator	30	None, on purpose. Email hello@embra.cloud with the operation_id

The environment is blocked after an incident with an unknown outcome (RECOVERY_REQUIRED or MIGRATION_UNKNOWN). Every change is refused until the Embra team has checked, including approving a pending deploy or import plan. The plan stays awaiting approval: once unblocked you can approve it again (if it has not expired). “Từ chối” (reject) still works. The overview shows “Đội Embra cần kiểm tra trước khi bạn deploy tiếp”, and the service shows “Chờ đội Embra kiểm tra” (waiting for the Embra team to check).

Sentence: Environment đang bị chặn sau một sự cố chưa rõ kết quả. Liên hệ đội Embra (hello@embra.cloud).

Retry? No. It is refused the same way until the environment is reopened.

Do NOT delete the environment. Email hello@embra.cloud with the operation ID of the first failed operation (the one marked “Cần đội Embra hỗ trợ” or “Cần xác minh dữ liệu” under “Lần deploy” (deploys)), the workspace, environment and time.

The sentence Database không ở trạng thái sẵn sàng (…). Liên hệ đội Embra (hello@embra.cloud). uses this code too: the environment’s database is in a failed state. Handle it the same way.

Other

OPERATION_IN_PROGRESS

HTTP	Auto retry	next_action	Exit code	Next step
409	No	wait	10	embra wait <op_id>

The environment has another operation still running (build, deploy, database creation, restore…), or it is being deleted. Wait for it to finish and try again. Follow progress under “Lần deploy” (deploys).

INVALID_INPUT

HTTP	Auto retry	next_action	Exit code	Next step
400	No	fix_input	2	Fix as described here, then retry

Invalid input: a name in the wrong format, a value out of range, a missing field. The sentence usually names the field. Fix it and try again.

Common sentences:

• “Environment đang tạm dừng. Chạy embra env resume trước khi deploy.”: turn the app back on first, then deploy.
• “Database đang dừng. Chạy embra db start trước khi fork.”: start the database first.
• Tối đa 100 file migration mỗi plan …, Tổng dung lượng migration vượt 2 MiB.: split it up; each file is at most 256 KiB.

NOT_FOUND

HTTP	Auto retry	next_action	Exit code	Next step
404	No	fix_input	1	Fix as described here, then retry

What you asked for (project, environment, domain, token…) was not found. It may have been deleted, or it belongs to another workspace. Check the name or ID, and that you are in the right workspace.

IDEMPOTENCY_CONFLICT

HTTP	Auto retry	next_action	Exit code	Next step
409	No	fix_input	10	Fix as described here, then retry

A repeated request used the same Idempotency-Key with different content, or the request already ran and its secret value cannot be returned again. Send a new request with a new key.

FORK_SECRET_IS_PROD

HTTP	Auto retry	next_action	Exit code	Next step
409	No	fix_input	10	Fix as described here, then retry

The value you set for a fork is the same as a production secret. Forks may not use real keys. Create a test or sandbox key at the provider (payments, email…) and set that instead.

RATE_LIMITED

HTTP	Auto retry	next_action	Exit code	Next step
429	Yes	wait	75	embra wait <op_id>, or wait and retry

Too many requests in a short time. Wait a few seconds and try again. Safe to retry.

TEMPORARILY_UNAVAILABLE

HTTP	Auto retry	next_action	Exit code	Next step
503	Yes	wait	75	embra wait <op_id>, or wait and retry

Part of Embra is not responding for the moment. Nothing changed. Wait a while and try again; safe to retry. If it lasts, email hello@embra.cloud.

API_UNREACHABLE

HTTP	Auto retry	next_action	Exit code	Next step
— (CLI)	Yes	fix_input	1	Check --api/EMBRA_API and the network, rerun

Raised by the CLI or embra mcp, not the server. The request was never sent: wrong API address (--api, EMBRA_API), no network, DNS or TLS failure. Nothing changed on Embra. Check the address and network, then rerun the same command.

WAIT_TIMEOUT

HTTP	Auto retry	next_action	Exit code	Next step
— (CLI)	Yes	wait	75	embra wait <op_id>, or wait and retry

Raised by the CLI or embra mcp. You used --wait, embra wait or embra_wait, and the --timeout ran out while the operation is still running. Nothing is broken. Keep waiting with embra wait <op_id>; do not rerun the command that created the operation.

INTERNAL

HTTP	Auto retry	next_action	Exit code	Next step
500	No	contact_operator	1	None, on purpose. Email hello@embra.cloud with the operation_id

An error on Embra’s side. Try once more. Still failing? Email hello@embra.cloud with the operation ID and time.

CLI exit codes

Use exit codes so CI scripts know what to do:

Exit code	Meaning
0	Done
1	Sign-in error, not found, cannot connect (API_UNREACHABLE), or an error on Embra’s side
2	Invalid input (INVALID_INPUT, REPO_CONFIG_INVALID, SOURCE_ARCHIVE_INVALID)
10	The action was refused or failed (most error codes)
20	Waiting for approval (APPROVAL_REQUIRED, MIGRATION_DATA_LOSS)
30	Needs the Embra team (RECOVERY_REQUIRED, MIGRATION_UNKNOWN, ENVIRONMENT_BLOCKED, suspensions)
75	Temporary, try again later (RATE_LIMITED, TEMPORARILY_UNAVAILABLE), or the wait ran out (WAIT_TIMEOUT)