Mã lỗi và cách sửa

Cách đọc lỗi

Mỗi lỗi gồm ba phần:

Phần	Ví dụ	Thấy ở đâu
Mã lỗi (reason_code)	HEALTHCHECK_FAILED	Output --json của CLI, và nội dung chép bằng “Sao chép diagnostic ID”
Câu tiếng Việt (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 và CLI
Bước tiếp (next_action)	fix_input	Dòng dưới câu lỗi trên console, dòng bước tiếp: trong CLI

next_action	Console ghi	CLI ghi	Nghĩa
fix_input	“Kiểm tra và sửa thông tin.”	sửa đầu vào rồi chạy lại	Sửa code, config hoặc input rồi làm lại
rerun_plan	“Tạo plan mới để kiểm tra lại.”	chạy lại plan	Plan cũ hết đúng, tạo plan mới
owner_review	“Cần owner hoặc admin xem và quyết định.”	chủ workspace cần xem và duyệt	Owner hoặc Admin cần approve hoặc nâng gói
wait	“Đang xử lý, vui lòng chờ.”	chờ rồi kiểm tra lại	Chờ một lúc rồi thử lại
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	Đội Embra cần xem. Xem Khi cần liên hệ
none		không cần làm gì thêm	Không có lỗi

Khối “Nội dung từ app — không do Embra viết” dưới câu lỗi là chữ lấy từ app hoặc repo của bạn: cuối build log, response app trả cho health check, lỗi Postgres, DNS record Embra đọc được. Nguyên nhân thật thường nằm ở đây.

Cách tìm mã

• Ctrl+F (Cmd+F trên Mac) rồi gõ mã lỗi, ví dụ BUILD_FAILED.
• Console chỉ hiện câu tiếng Việt? Gõ vài chữ đầu của câu đó: mỗi mục bên dưới có ghi câu bạn hay thấy.
• Mỗi mã có URL riêng: docs.embra.cloud/loi/#<mã viết thường>, ví dụ /loi/#healthcheck_failed.

Khi cần liên hệ

Email hello@embra.cloud, kèm:

1. Mã operation (operation_id): dòng operation: trong CLI, hoặc nội dung chép bằng “Sao chép diagnostic ID” trên console.
2. Workspace, project, environment (ví dụ shop/production).
3. Giờ gặp lỗi, ghi rõ giờ Việt Nam hay UTC.
4. Mã lỗi và câu lỗi, nếu có.

Lỗi cần đội Embra (contact_operator) thì console có nút “Liên hệ hỗ trợ”, mở email nháp đã điền sẵn mã operation và mã lỗi. Email nháp chỉ có mã, không có secret hay data của bạn.

Build và deploy

BUILD_FAILED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	fix_input	10	Sửa theo mục này rồi làm lại

Không build được image từ code. App đang chạy không bị ảnh hưởng.

Câu bắt đầu bằng embra.toml: thì xem REPO_CONFIG_INVALID. Các câu khác:

Câu lỗi	Nghĩa
buildctl lỗi: exit … hoặc build trong VM không thành công.	Lệnh build (Dockerfile hoặc Railpack) fail. Nguyên nhân nằm trong build log
railpack prepare lỗi: exit …	Bước Railpack phân tích repo fail. Lý do nằm trong build log
git fetch lỗi: …, git checkout lỗi: …	Embra không lấy được commit từ GitHub
không thấy Dockerfile.	embra.toml đặt builder = "dockerfile" nhưng không có file ở path đó
root không tồn tại., root không phải thư mục., root trỏ ra ngoài repo.	root trong embra.toml hoặc Root directory sai
Image build ra vượt giới hạn dung lượng của gói.	Image lớn hơn dung lượng đĩa của gói
… file migration không hợp lệ., migration trùng tên., quá 100 file migration., migration … vượt … byte.	Thư mục migration có vấn đề. Xem Viết migration
preview.seed không tồn tại.	File khai ở [preview] seed không có trong repo
Upload của build này không còn tồn tại. Upload lại rồi build.	Bản upload từ embra deploy đã hết hạn

Cách sửa:

1. Bấm “Xem build logs”, đọc từ dưới lên. Dòng lỗi đầu tiên của npm, pip, go, docker thường là nguyên nhân.
2. Chạy lại đúng lệnh build đó trên máy. Repo có Dockerfile thì chạy docker build . ở thư mục gốc (hoặc ở root).
3. Log có egress từ chối "<host>": build cần tải từ host chưa được mở. Gửi tên host tới hello@embra.cloud. Host đang mở: Embra build app thế nào.
4. Image quá lớn: dùng Dockerfile multi-stage chỉ copy thư mục build (ví dụ dist/) vào stage cuối, cài dependency production (npm ci --omit=dev), thêm .dockerignore bỏ node_modules, .git, file test.
5. builder = "dockerfile" mà không có Dockerfile: bỏ dòng builder để Embra tự chọn Railpack, hoặc sửa dockerfile đúng path tính từ root.
6. Commit và push lại.

Dockerfile multi-stage mẫu cho app Node

# 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 an toàn? Có. Build fail thì không deploy gì, database không bị đụng.

Retry? Cùng commit thường ra cùng lỗi. Riêng không khởi động được VM., VM tắt trước khi sẵn sàng., mất kết nối với embra-buildd giữa chừng build. là lỗi phía Embra: bấm “Build lại” một lần.

Liên hệ khi: lỗi phía Embra lặp lại sau khi build lại, hoặc build chạy được trên máy bạn mà fail trên Embra và log không chỉ ra lý do.

BUILD_TIMEOUT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	fix_input	10	Sửa theo mục này rồi làm lại

Build chạy quá giờ nên bị dừng. Câu lỗi: build vượt thời gian cho phép. Thời gian build tối đa theo gói, không quá 25 phút. App đang chạy không bị ảnh hưởng.

Nguyên nhân	Cách sửa
Cài dependency không có lockfile, phải resolve lại cả cây	Commit lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, poetry.lock…)
Chạy test, lint hoặc tải data lớn trong bước build	Chuyển test, lint sang CI
Lệnh trong Dockerfile chờ host chưa được mở tới hết giờ (log có egress từ chối)	Gửi tên host tới hello@embra.cloud
Dockerfile copy cả code trước khi cài dependency, sửa code là cài lại từ đầu	Copy file khai dependency và cài trước, copy code sau (mẫu dưới)

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

Mở “Xem build logs” để thấy build dừng ở bước nào, sửa rồi push lại.

Data an toàn? Có. Không deploy gì.

Liên hệ khi: build dừng ở bước tải package từ host đã mở, hoặc build dưới 25 phút trên máy bạn mà vẫn hết giờ trên Embra.

HEALTHCHECK_FAILED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	fix_input	10	Sửa theo mục này rồi làm lại

App mới chạy lên nhưng không trả lời health check đúng, nên Embra không chuyển traffic sang (hoặc đã trả traffic về bản cũ).

Câu lỗi	App lúc này
Bản mới không qua readiness trong thời gian khởi động. Bản cũ vẫn phục vụ.	Bản cũ vẫn chạy. Deploy đầu thì chưa có bản nào chạy
Bản mới lỗi sau khi nhận traffic, route đã được trả về bản cũ.	Bản mới lỗi trong 30 giây theo dõi, traffic đã về bản cũ
App không qua readiness sau khi chạy lại; app vẫn đang tạm dừng.	Bạn bật lại app đang tạm dừng nhưng app không lên, app vẫn tắt
App không chạy được trên bản khôi phục (không qua readiness). …	Restore bị huỷ, app và database cũ vẫn chạy
Deploy đã xong nhưng app chưa trả lời kiểm tra sức khoẻ sau 2 phút. … (CLI)	embra deploy chờ 2 phút mà app chưa healthy. Xem app log

Embra gọi GET tới health_path mỗi 2 giây, cần 3 lần 2xx liên tiếp trong startup_grace_seconds (mặc định 60 giây). Chi tiết: Health check.

Nguyên nhân	Cách sửa
App listen 127.0.0.1 hoặc localhost, ngoài container không gọi được	Listen 0.0.0.0 (mẫu theo framework bên dưới)
App listen port khác [deploy] port (mặc định 3000), ví dụ port mặc định của framework (8000, 8080, 5173)	Đọc port từ env var PORT. Embra đặt PORT bằng [deploy] port, trừ khi bạn tự đặt secret PORT
health_path trả 3xx: redirect sang trang login, sang HTTPS hoặc thêm /. Redirect không tính là đạt	Làm route riêng, ví dụ /healthz, trả 2xx, không login, không redirect
health_path trả 4xx: route không tồn tại, cần login, hoặc framework chặn header Host lạ. Embra gọi thẳng IP nội bộ của container, nên Host là IP:cổng, không phải domain của bạn	Như trên; với Django xem middleware mẫu bên dưới
App crash khi start: thiếu secret, không connect được database, chạy migration lúc start (user database của app không có quyền đổi schema)	Đọc app log. Bỏ lệnh migration lúc start (prisma migrate deploy, TypeORM synchronize: true…): migration đi qua Embra, xem Database và migration
App start chậm hơn startup_grace_seconds	Tăng startup_grace_seconds (tối đa 300)

Cách sửa:

1. Mở “Logs”, đọc app log quanh giờ deploy fail. Crash khi start hiện rõ ở đây.

2. Xem khối “Nội dung từ app — không do Embra viết”: response app trả ở lần health check cuối.

3. Sửa theo bảng trên, khai route health check trong embra.toml:

   [deploy]
   health_path = "/healthz"

4. Push lại.

Mẫu listen 0.0.0.0:$PORT theo 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}"
  }
}

Dùng output: 'standalone' và chạy node server.js trong Dockerfile thì đặt thêm HOSTNAME:

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

Django (gunicorn, trong Dockerfile):

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

Django trả 400 khi Host không có trong ALLOWED_HOSTS, và có thể redirect sang HTTPS nếu bật SECURE_SSL_REDIRECT. Cho health check một middleware riêng, đặt đầu tiên trong 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 (trong Dockerfile):

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

$PORT trong dạng mảng

CMD ["node", "server.js"] và start = ["node", "dist/main.js"] trong embra.toml là dạng mảng, không qua shell, nên $PORT trong đó không được thay bằng giá trị. Đọc PORT trong code, hoặc bọc bằng shell: CMD ["sh", "-c", "gunicorn myproject.wsgi --bind 0.0.0.0:$PORT"].

Data an toàn? Tuỳ trường hợp:

• Bản mới không qua health check: chưa có traffic thật tới bản mới. Nhưng app mới đã chạy code start với DATABASE_URL, nên data code đó ghi (ví dụ seed lúc start) vẫn còn.
• Bản mới lỗi sau khi nhận traffic: bản mới đã phục vụ request thật lúc được theo dõi. Data ghi lúc đó vẫn còn trong database.
• Mọi trường hợp: plan có migration thì migration đã chạy vẫn giữ nguyên, bản cũ đang chạy trên schema mới. Đừng sửa file migration đã chạy để “hoàn tác”, Embra sẽ báo MIGRATION_HISTORY_CHANGED. Muốn đổi lại schema thì thêm file migration mới.

Retry? Không, khi chưa sửa gì: health check chạy lại sẽ fail y như cũ.

Liên hệ khi: app chạy đúng 0.0.0.0:$PORT và trả 2xx ở health_path khi chạy bằng Docker trên máy bạn, mà Embra vẫn báo lỗi.

REPO_CONFIG_INVALID

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
400	Không	fix_input	2	Sửa theo mục này rồi làm lại

embra.toml có lỗi. Câu lỗi luôn bắt đầu bằng embra.toml: và nêu tên field sai. Phát hiện lúc build thì bạn thấy mã BUILD_FAILED với cùng câu.

Câu lỗi (ví dụ)	Cách sửa
embra.toml: field lạ deploy.prot.	Sửa tên field (ở đây là port). Embra không bỏ qua field lạ
embra.toml: field deploy.port sai kiểu giá trị.	Sửa kiểu: port = 3000, không phải port = "3000"
embra.toml: sai cú pháp TOML ở dòng 12.	Sửa cú pháp ở đúng dòng đó (thiếu ngoặc kép, thiếu ]…)
embra.toml: build.builder phải là "railpack" hoặc "dockerfile".	Sửa giá trị, hoặc bỏ dòng để Embra tự chọn
embra.toml: deploy.startup_grace_seconds phải > 0.	Đặt từ 5 tới 300 giây
embra.toml: … phải là đường dẫn tương đối trong repo., … không được trỏ ra ngoài repo.	Path tính từ gốc repo (hoặc từ root), không bắt đầu bằng /, không dùng .. ra ngoài
embra.toml: build.env.EMBRA_…: tiền tố EMBRA_ dành riêng cho Embra.	Đổi tên biến
embra.toml: cron.<tên>.schedule: …	Cron 5 field, giờ UTC, cách nhau ít nhất 5 phút
embra.toml: file vượt 65536 byte.	Rút gọn file, tối đa 64 KiB

So với tham chiếu embra.toml. Kiểm cú pháp trên máy, ví dụ python3 -c "import tomllib; tomllib.load(open('embra.toml','rb'))", rồi commit và push lại.

Data an toàn? Có. Không deploy gì.

SOURCE_NOT_CONNECTED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	fix_input	10	Sửa theo mục này rồi làm lại

Embra không đọc được repo GitHub của environment này.

Câu lỗi:

• 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.

Nguyên nhân hay gặp:

• Embra GitHub App bị gỡ hoặc tạm dừng ở account hoặc organization.
• Lúc cài GitHub App bạn chọn “Only select repositories” và repo này không có (hoặc vừa bị bỏ ra).
• Repo bị đổi tên, chuyển owner hoặc bị xoá. Branch đã connect bị đổi tên hoặc xoá.
• Bạn login Embra bằng Google. Chỉ người login bằng GitHub mới connect được repo.

Cách sửa:

1. Mở Cài đặt → “Source code” → “Cài / cập nhật quyền GitHub App”.
2. Cấp lại quyền cho repo trên GitHub.
3. Kiểm tên repo và branch còn đúng. Branch đổi tên thì connect lại branch mới.
4. Bấm “Build lại”.

Xem thêm Deploy từ GitHub.

Data an toàn? Có. App đang chạy vẫn chạy, chỉ không build được bản mới.

SECRET_REVOKED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	fix_input	10	Sửa theo mục này rồi làm lại

Một secret mà bản deploy cần đã bị thu hồi, hoặc chưa có version nào còn hiệu lực. Ví dụ: Một secret của release đã bị thu hồi sau khi plan. Đặt version mới rồi plan lại. hoặc Secret <TÊN> chưa có version nào còn hiệu lực. …

1. Mở Cài đặt → “Secrets”, nhập giá trị mới, bấm “Lưu secret”.
2. Bấm “Build lại” để tạo plan mới. Secret vào app ở lần build kế tiếp.

Xem Secret. Bật lại app đang tạm dừng mà gặp lỗi này thì app vẫn tắt tới khi bạn sửa.

ATTESTATION_MISMATCH

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	contact_operator	10	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Container mới chạy lệch config Embra đã yêu cầu, nên Embra không chuyển traffic sang. Bản cũ vẫn chạy. Đây là kiểm tra an toàn phía Embra, sửa code không giải quyết được. Email hello@embra.cloud kèm mã operation.

IMAGE_DIGEST_REQUIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
400	Không	fix_input	10	Sửa theo mục này rồi làm lại

embra deploy --image cần image pin theo digest: <image>@sha256:<64 ký tự hex>, không dùng tag như :latest.

SOURCE_ARCHIVE_INVALID

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
400	Không	fix_input	2	Sửa theo mục này rồi làm lại

Source mà embra deploy upload bị từ chối (không phải tar.gz hợp lệ, hoặc có loại file không được phép). Bỏ file lạ khỏi thư mục hoặc thêm vào .embraignore, rồi chạy lại.

SOURCE_TOO_LARGE

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
422	Không	fix_input	10	Sửa theo mục này rồi làm lại

File upload vượt giới hạn của gói: source của embra deploy, hoặc file dump khi nhập data (lớn hơn dung lượng database của gói). Câu lỗi ghi rõ cỡ file và giới hạn. Thu nhỏ file (thêm .embraignore, bỏ bảng không cần), hoặc nâng gói.

Database và migration

Câu lỗi migration đôi khi ghi “lớp” của câu lệnh. Đối chiếu với Embra kiểm migration thế nào:

Lớp	Nhóm
A	An toàn
B	Đổi hoặc xoá data
C	Khoá bảng lâu
D	Không chạy trong transaction
E, F	Chưa hỗ trợ (E: Embra không parse được câu lệnh; F: bị cấm)

MIGRATION_UNSUPPORTED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
422	Không	fix_input	10	Bỏ câu lệnh lớp E/F, push lại

Một câu lệnh trong file migration thuộc loại Embra chưa chạy được, nên plan bị từ chối trước khi đụng database. Sau build thành công, console hiện “Build xong · cần sửa config” và “Không tạo được plan deploy”.

Câu lỗi:

• File 0003_x.sql, câu lệnh #2 (CreateFunctionStmt) lớp E: … hoặc … 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.

Nguyên nhân	Cách sửa
File có function, procedure, trigger, view, khối DO, CREATE EXTENSION, CREATE SCHEMA, GRANT/REVOKE hoặc COPY (migration do ORM sinh hay có)	Chuyển logic đó vào code app. Embra chưa chạy được các câu này
File có BEGIN/COMMIT	Bỏ đi. Embra tự bọc mỗi file trong một transaction
CREATE INDEX CONCURRENTLY chung file với câu khác	Tách ra file riêng, chỉ có đúng câu đó
SQL viết cho database khác (MySQL, SQLite) hoặc cú pháp Postgres không parse được	Viết lại bằng SQL Postgres

Tìm câu lệnh theo số # (tính từ 1) trong file mà câu lỗi nêu; câu gốc nằm trong khối “Nội dung từ app — không do Embra viết”. File này chưa từng chạy nên sửa thẳng được, rồi commit và push lại.

Data an toàn? Có. Embra từ chối từ bước lập plan. Riêng SQL của migration đã thay đổi bảng nội bộ của Embra. xảy ra lúc chạy, và Embra đã rollback câu lệnh đó.

MIGRATION_REHEARSAL_FAILED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	fix_input	10	Sửa SQL, kiểm bằng embra plan rồi push

Migration chạy lỗi:

Câu lỗi	Lỗi ở đâu
Diễn tập migration thất bại trên bản sao dữ liệu; chưa đụng production. …	Trên bản sao data. Production chưa bị đụng
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.	Trên production. Câu lệnh lỗi đã rollback

Lỗi Postgres (ví dụ column "status" of relation "orders" contains null values) nằm trong khối “Nội dung từ app — không do Embra viết”, kèm tên file và câu lệnh lỗi.

Nguyên nhân hay gặp:

• Thêm cột NOT NULL không có DEFAULT vào bảng đã có data.
• Tạo UNIQUE hoặc foreign key khi data hiện có vi phạm (trùng giá trị, tham chiếu dòng không tồn tại).
• Đổi kiểu cột mà data cũ không convert được (ví dụ chữ sang số).
• Tham chiếu bảng hoặc cột chưa có, do thứ tự file sai.
• Migration chạy được trên database rỗng ở máy bạn nhưng fail với data thật.

Cách sửa: sửa SQL cho chạy được với data hiện có. Ví dụ thêm cột bắt buộc theo ba bước:

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;

Hoặc gọn hơn: ALTER TABLE orders ADD COLUMN status text NOT NULL DEFAULT 'paid';

File lỗi chưa được áp nên sửa thẳng được. Đừng sửa file đã áp ở các lần deploy trước. Commit và push lại, Embra diễn tập lại trước khi chạy.

Data an toàn? Lỗi lúc diễn tập: production không bị đụng. Lỗi trên production: câu lệnh lỗi đã rollback, code cũ vẫn chạy. Mỗi file chạy trong transaction riêng, nên plan nhiều file thì các file trước file lỗi có thể đã áp; Embra ghi nhận và lần sau chỉ chạy các file còn lại.

Liên hệ khi: lỗi trên production mà bạn không tìm ra production khác bản sao ở đâu.

MIGRATION_LOCK_TIMEOUT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	rerun_plan	10	Tạo plan mới: “Build lại” hoặc embra build

Migration cần khoá bảng nhưng có query khác giữ khoá quá lâu. Embra thử lại nhiều lần với timeout ngắn để không treo app, rồi dừng.

Câu lỗi: 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ụ.

Nguyên nhân: transaction mở lâu hoặc connection “idle in transaction” (mở transaction mà không commit); query báo cáo hoặc export dài trên bảng đó; cron hoặc worker đang xử lý hàng loạt trên bảng đó.

Cách sửa:

1. Dừng query dài: kết thúc job báo cáo, hoặc sửa code mở transaction mà không đóng.
2. Chọn lúc ít traffic.
3. Tạo plan mới: bấm “Build lại”, hoặc chạy embra build.

Data an toàn? Có. File đang chờ khoá chưa chạy, không file nào áp dở, code cũ vẫn chạy. Plan nhiều file thì các file trước có thể đã áp; plan sau chỉ chạy các file còn lại.

Retry? Có, sau khi query dài đã xong.

MIGRATION_DATA_LOSS

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
202	Không	owner_review	20	Approve trên web, gõ CONFIRM_MIGRATION

Không phải lỗi: plan đang chờ approve, và diễn tập cho thấy migration sẽ xoá hoặc ghi đè data (ví dụ DROP COLUMN, DROP TABLE, DELETE). Áp dụng cả ở staging.

1. Bấm “Xem và duyệt”, đọc phần data sẽ mất: bảng, cột, số dòng ước tính.
2. Cần giữ data đó thì lấy ra trước: Cài đặt → “Dữ liệu” → “Export dữ liệu”, hoặc copy sang bảng khác bằng một migration riêng.
3. Đồng ý: gõ tên environment và CONFIRM_MIGRATION, bấm “Duyệt và deploy”.
4. Không đồng ý: bấm “Từ chối” rồi sửa migration.

Chỉ Owner hoặc Admin approve được. Xem Duyệt production.

Data an toàn? Chưa chạy gì tới khi bạn approve. Migration áp rồi thì bạn không tự restore về mốc trước migration được (xem MIGRATION_AFTER_RESTORE_POINT), nên chắc chắn trước khi approve.

MIGRATION_HISTORY_CHANGED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	fix_input	10	git checkout <commit> -- migrations/<file>

File migration trong repo không khớp với những gì đã chạy trên environment.

Câu lỗi	Cách sửa
File 0002_x.sql đã áp lên environment nhưng nội dung đã đổi. …	Trả file về đúng nội dung đã chạy (ví dụ git checkout <commit cũ> -- migrations/0002_x.sql). Muốn đổi tiếp thì thêm file mới
File đã áp lên environment bị thiếu trong plan: … Giữ nguyên mọi file đã áp.	Khôi phục file đã xoá hoặc đổi tên về đúng tên cũ
File mới 0003_x.sql nằm trước file đã áp 0005_y.sql. Đặt số lớn hơn 0005_y.sql.	Đổi tên file mới với số lớn hơn file đã áp cuối cùng

Nguyên nhân hay gặp:

• Sửa file migration đã chạy để “sửa lỗi”.
• Gộp, xoá hoặc đổi tên migration cũ cho gọn.
• Dùng Prisma và chạy lại script copy migration sau khi xoá hoặc sửa migration cũ của Prisma, làm lệch số thứ tự. Xem Viết migration.
• Hai branch cùng thêm migration, branch merge sau có số nhỏ hơn.

Data an toàn? Có. Embra từ chối từ bước lập plan, chưa chạy gì.

SCHEMA_DRIFT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	rerun_plan	10	Tạo plan mới: “Build lại” hoặc embra build

Schema production đã đổi kể từ lúc diễn tập, nên kết quả diễn tập hết đúng và plan bị huỷ. Chưa file nào được áp. Tạo plan mới (bấm “Build lại”, hoặc embra build) để Embra diễn tập lại.

POOL_IOPS_BUDGET_EXCEEDED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
422	Không	contact_operator	10	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Server đã dùng hết budget ghi đĩa nên chưa dựng được Postgres. Đây là giới hạn phía Embra. Email hello@embra.cloud kèm mã operation.

Domain

DOMAIN_NOT_VERIFIED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	fix_input	10	Sửa theo mục này rồi làm lại

Embra chưa verify được domain. Cần cả hai: TXT record đúng, và domain trỏ về Embra. Câu lỗi nêu chính xác phần còn thiếu, ví dụ:

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).

Giá trị DNS Embra đọc được nằm trong khối “Nội dung từ app — không do Embra viết”.

Nguyên nhân	Cách sửa
DNS chưa propagate xong (thường 5–30 phút)	Đợi vài phút
Bật Cloudflare proxy (mây cam), Embra chỉ thấy IP Cloudflare	Chuyển record sang DNS only (mây xám)
TXT record bị nhân đôi đuôi: nhiều nhà cung cấp tự thêm tên domain, gõ cả tên đầy đủ thành _embra-challenge.www.shop.vn.shop.vn	Ô “Tên” tự thêm đuôi thì chỉ gõ _embra-challenge.www (hoặc _embra-challenge với tên gốc)
Dùng CNAME cho tên gốc (shop.vn)	Tên gốc dùng A record tới IP Embra hiện trên màn hình
Còn A hoặc CNAME cũ trỏ chỗ khác	Xoá record cũ cùng tên

Record Embra yêu cầu nằm ở Cài đặt → “Domain”. Sửa xong bấm “Kiểm tra”; mỗi domain kiểm tra tối đa 1 lần mỗi 30 giây. Xem Domain riêng.

Data an toàn? Có. App vẫn chạy ở địa chỉ .onembra.com.

DOMAIN_TAKEN

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	fix_input	10	Sửa theo mục này rồi làm lại

Domain đã được verify ở một environment khác trên Embra; một domain chỉ gắn được vào một app. Câu lỗi: Hostname này đã được xác minh ở một environment khác.

Nguyên nhân: domain còn gắn ở app cũ, ở staging, hoặc ở workspace khác của bạn (ví dụ workspace dùng thử); hoặc người khác đã verify domain này trước.

Cách sửa:

1. Domain đang gắn ở app khác của bạn: mở Cài đặt → “Domain” ở app đó, bấm “Xoá”.
2. Quay lại app mới, thêm domain lần nữa.

Bạn không gắn domain này ở đâu cả thì email hello@embra.cloud kèm tên domain. Embra không cho biết domain đang nằm ở workspace nào.

Data an toàn? Có. App vẫn chạy ở .onembra.com. Retry không có tác dụng tới khi domain được gỡ ở nơi kia.

Tài khoản và gói

QUOTA_EXCEEDED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
422	Không	owner_review	10	Owner hoặc Admin xem trên web

Vượt giới hạn của gói hoặc của server. Câu lỗi ghi rõ giới hạn nào, thường kèm con số.

Câu lỗi (ví dụ)	Cách xử lý
Gói dùng thử chỉ có một environment …, Gói dùng thử cho tối đa …	Nâng gói, hoặc xoá thứ không dùng. Xem Gói dùng thử
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 …	Giảm cỡ app khác ở Cài đặt → “Tài nguyên”, hoặc nâng gói
Gói … có tối đa … database cho app production …	Xoá database không dùng, hoặc nâng gói. Staging và preview không tính
Workspace đã dùng hết số domain riêng của gói …	Gỡ domain không dùng, hoặc nâng gói
Gói … không có staging. …, Mỗi project có tối đa một staging. …	Nâng gói, hoặc xoá staging cũ
Gói … cho tối đa … preview environment …	Đóng bớt PR, hoặc chờ preview cũ tự xoá
Gói … không có object storage., Environment đã có bucket; …	Xem Lưu file
Sau build thành công, console hiện “Không tạo được plan deploy” vì worker hoặc cron	Bớt [processes.*] hoặc [cron.*] trong embra.toml cho vừa gói, hoặc nâng gói, rồi push lại
Gói hiện tại giữ … ngày lịch sử log …, … ngày lịch sử metrics …	Chọn khoảng thời gian gần hơn
Workspace đang mở … luồng log, tối đa cho phép. …	Đóng bớt tab đang xem log
Verify quá dày. …	Mỗi domain kiểm tra 1 lần mỗi 30 giây, mỗi workspace có giới hạn số lần mỗi giờ. Chờ rồi bấm “Kiểm tra” lại
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 …	Giới hạn của server, không phải của gói. 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. …	App và database hiện tại vẫn chạy bình thường. Email hello@embra.cloud nếu cần rollback gấp

Nâng gói: chỉ Owner, trên browser, ở menu tài khoản → “Thanh toán”. Xem Tài khoản, dùng thử và thanh toán.

Data an toàn? Có. Embra từ chối trước khi làm, không có gì thay đổi.

TRIAL_EXPIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	owner_review	10	Owner hoặc Admin xem trên web

Hết 7 ngày dùng thử. Console hiện “Dùng thử đã hết hạn”.

Câu lỗi: 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.

• Mọi thao tác bị từ chối, kể cả xem. Riêng Owner vẫn xem được thông tin thanh toán và chuyển sang workspace khác.
• Sau đó cả workspace bị xoá: app, database và backup.
• Đã chọn gói trước khi hết hạn: Embra giữ workspace thêm 72 giờ chờ tiền về. Màn hình hiện mã chuyển khoản, QR, số tiền và giờ xoá. Chuyển khoản trước giờ đó thì workspace mở lại. Chuyển thiếu thì workspace không bị xoá nhưng vẫn khoá: email hello@embra.cloud.

Cách xử lý:

1. Chưa chọn gói mà cần giữ app hoặc data: email ngay hello@embra.cloud kèm tên workspace. Màn hình này có nút “Liên hệ hỗ trợ”.
2. Workspace dùng thử khác: chọn gói và chuyển khoản trước khi hết hạn. Xem Gói dùng thử.

Retry? Không. Mọi request tới workspace này đều bị từ chối.

SIGNUP_CLOSED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	contact_operator	10	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Embra chưa cho account này vào. Console hiện “Chưa vào được Embra”.

Câu lỗi	Cách xử lý
Email Google này chưa được mời vào workspace nào. …	Login Google chỉ dành cho người được mời. Nhờ Owner mời đúng email đó, hoặc login bằng 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.	Gửi username GitHub tới hello@embra.cloud để được mở riêng
Đợt dùng thử hôm nay đã đầy. …	Thử lại hôm sau, hoặc email hello@embra.cloud để được mời
Đăng ký dùng thử đang đóng. …	Email hello@embra.cloud để được mời

Xem Đăng nhập.

Retry? Chỉ khi lượt dùng thử trong ngày đã đầy: thử lại hôm sau. Các trường hợp khác cần lời mời hoặc email đội Embra trước. Chưa có workspace nào được tạo nên không data nào bị ảnh hưởng.

WORKSPACE_DELETED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	contact_operator	10	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Account vẫn còn nhưng mọi workspace của nó đã bị xoá: tự xoá, hoặc trial hết hạn và bị dọn sau thời gian giữ. Console hiện “Workspace của bạn đã bị xoá”.

Trial chỉ có một lần mỗi account. Email hello@embra.cloud để mở workspace mới có gói trả phí. Data của workspace đã xoá không khôi phục được.

Từ bản Embra có T254, login lại tự mở một workspace chưa có gói (xem PLAN_REQUIRED); mã này chỉ còn ở bản cũ.

Retry? Không. Login lại vẫn ra lỗi này cho tới khi có workspace mới.

PLAN_REQUIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	owner_review	10	Owner hoặc Admin xem trên web

Workspace chưa có gói (“Chưa có gói”). Embra mở workspace này khi bạn đăng nhập lại mà mọi workspace trước đã bị xoá: dùng thử chỉ có một lần mỗi account. Workspace chưa có gói không tạo được project, environment hay fork.

Owner vào Thanh toán, chọn gói và chuyển khoản theo mã VietQR. Tiền về thì gói kích hoạt, tạo project được ngay.

Retry? Không. Chọn và trả gói trước, rồi làm lại thao tác.

WORKSPACE_SUSPENDED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	contact_operator	30	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Đội Embra đã tạm ngưng workspace, thường sau một báo cáo lạm dụng.

Câu lỗi: 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.

• App ngừng nhận traffic. Data được giữ nguyên.
• Vẫn xem được, nhưng không deploy, đổi config hay đổi gói được.

Cách xử lý: email abuse@embra.cloud kèm tên workspace, giải thích app làm gì và vì sao bạn cho rằng tạm ngưng là nhầm.

Retry? Không. Mọi thao tác ghi bị từ chối tới khi đội Embra gỡ tạm ngưng.

ENVIRONMENT_SUSPENDED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	contact_operator	30	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Như WORKSPACE_SUSPENDED nhưng chỉ một environment. App của environment đó ngừng nhận traffic, data được giữ nguyên. Khiếu nại qua abuse@embra.cloud.

Quyền và duyệt

APPROVAL_REQUIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
202	Không	owner_review	20	Owner hoặc Admin xem trên web

Không phải lỗi: plan đang chờ Owner hoặc Admin approve. Production luôn cần approve, kể cả không có migration. Staging và preview cần approve khi migration đổi hoặc xoá data.

1. Mở trang Tổng quan bằng account Owner hoặc Admin → “Xem và duyệt”.
2. Xem thay đổi code, config, data.
3. Gõ tên environment → “Duyệt và deploy”.

Developer và AI agent tạo được plan nhưng không approve được. Plan chờ quá 24 giờ thì hết hạn. Approve cần người thật vừa login: xem Việc cần người thật.

Data an toàn? Có. Chưa chạy gì tới khi được approve. App đang chạy vẫn chạy.

APPROVAL_EXPIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	rerun_plan	10	Tạo plan mới: “Build lại” hoặc embra build

Việc chờ approve đã quá hạn nên bị huỷ. Không có gì được áp dụng.

Câu lỗi	Cách xử lý
Plan đã hết hạn duyệt nên bị huỷ. …	Tạo plan mới: bấm “Build lại”, hoặc embra build
Bằng chứng diễn tập migration đã hết hạn nên plan bị huỷ. …	Tạo plan mới. Kết quả diễn tập chỉ dùng được 24 giờ
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 file lại để nhập
Restore đã hết hạn duyệt nên bị huỷ …	Tạo lại bản restore ở “Khôi phục dữ liệu…”
Request fork đã quá hạn duyệt …	Tạo lại request fork

Data an toàn? Có. Việc bị huỷ chưa đụng app hay database đang chạy. Không approve lại plan cũ được: phải tạo plan mới.

GENERATION_CONFLICT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	rerun_plan	10	Tạo plan mới: “Build lại” hoặc embra build

Environment đã đổi từ lúc lập plan (ví dụ có deploy hoặc rollback khác vừa xong), nên plan cũ bị huỷ để không approve nhầm. Tạo plan mới.

BINDING_MISMATCH

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	rerun_plan	10	Tạo plan mới: “Build lại” hoặc embra build

Bạn approve một version plan khác version đang chờ (thường do trang đã cũ). Reload trang, xem lại plan rồi approve.

FORBIDDEN_SCOPE

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	owner_review	10	Owner hoặc Admin xem trên web

Role hoặc token của bạn không có quyền làm việc này. Nhờ Owner hoặc Admin làm, hoặc nâng role. Xem Thành viên và phân quyền.

HUMAN_REQUIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	fix_input	10	Sửa theo mục này rồi làm lại

Việc này cần người thật, mà bạn đang dùng token máy (CI, agent). Làm trên browser, hoặc chạy embra login rồi thử lại. Xem Việc cần người thật.

REAUTH_REQUIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	fix_input	10	Sửa theo mục này rồi làm lại

Lần login đã quá 12 giờ, mà việc này cần người vừa login. Console: bấm “Đăng nhập lại bằng GitHub” (hoặc “Đăng nhập lại bằng Google”) ngay dưới câu lỗi. CLI: chạy lại embra login.

LAST_OWNER

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	fix_input	10	Sửa theo mục này rồi làm lại

Thay đổi này làm workspace (hoặc account agency) không còn owner. Nâng người khác lên owner trước, rồi làm lại.

UNAUTHENTICATED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
401	Không	fix_input	1	embra login hoặc token mới

Thiếu token, token sai hoặc hết hạn. Login lại trên console, chạy embra login, hoặc dùng token còn hạn.

CSRF_FAILED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	fix_input	1	Sửa theo mục này rồi làm lại

Browser gửi request không kèm mã bảo vệ hợp lệ, thường do tab mở quá lâu hoặc mở từ trang khác. Reload trang rồi thử lại.

DEVICE_ACCESS_DENIED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
403	Không	fix_input	1	Sửa theo mục này rồi làm lại

Bạn đã bấm từ chối khi duyệt login CLI. Chạy lại embra login nếu đó là máy của bạn.

DEVICE_CODE_EXPIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
400	Không	fix_input	1	Sửa theo mục này rồi làm lại

Mã login CLI hết hạn trước khi bạn duyệt trên browser. Chạy lại embra login để lấy mã mới.

Rollback và khôi phục

ROLLBACK_INCOMPATIBLE

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	owner_review	10	Sửa bằng commit mới

Không rollback được về bản đã chọn vì đã có migration chạy sau bản đó. Rollback chỉ trả code, không trả schema: code cũ có thể không chạy được trên schema mới.

Câu lỗi:

• Đã 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.

Danh sách migration nằm trong khối “Nội dung từ app — không do Embra viết”.

Cách xử lý:

1. Fix bằng commit mới chạy được với schema hiện tại, rồi deploy như bình thường.
2. Thật sự cần schema cũ thì viết migration mới đổi ngược lại.
3. Cần data trước migration đó thì email hello@embra.cloud kèm mã operation.

Data an toàn? Có. Embra từ chối trước khi làm gì.

ROLLBACK_DB_GONE

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	owner_review	10	Owner hoặc Admin xem trên web

Bản đích của rollback dùng database cũ (từ trước một lần restore), nhưng database đó đã bị xoá khi hết hạn giữ. Data cũ chỉ còn trong bản export bạn lấy trước đó. Xem Backup và khôi phục.

RESTORE_POINT_UNAVAILABLE

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
422	Không	fix_input	10	embra db restore-points

Mốc restore bạn chọn không dùng được: chưa có đủ backup, hoặc mốc nằm ngoài khoảng restore được. Câu lỗi ghi khoảng hợp lệ. Mở “Xem mốc khôi phục” và chọn mốc trong khoảng đó.

MIGRATION_AFTER_RESTORE_POINT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	owner_review	10	Chọn mốc sau migration

Có migration chạy sau mốc bạn chọn. Restore về mốc đó sẽ mất cấu trúc bảng mà app hiện tại cần, nên Embra chặn. Database và app đang chạy không bị đụng. Chọn mốc sau migration mà câu lỗi nêu. Cần data trước mốc đó thì email hello@embra.cloud.

RESTORE_SHORT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	contact_operator	10	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Backup thiếu data (WAL) trước mốc đã chọn nên không dựng được bản restore tới đúng mốc. Production không bị đụng. Email hello@embra.cloud kèm mã operation và mốc bạn chọn.

BACKUP_WAL_GAP

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	contact_operator	10	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Lần restore thử tự động gần nhất phát hiện backup thiếu một đoạn data. Console hiện “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.” App và database đang chạy không bị ảnh hưởng, nhưng đừng dựa vào khoảng restore tới khi đội Embra kiểm tra. Email hello@embra.cloud.

BACKUP_DATA_CORRUPT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	contact_operator	10	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Lần kiểm khôi phục tự động dựng được database, nhưng pg_amcheck đọc hết các trang và index thì thấy trang dữ liệu hỏng ngay trên database đang chạy, không phải trong backup. Nguyên nhân thường là lỗi đĩa hoặc bộ nhớ ở tầng dưới, hiếm khi do app.

• App vẫn chạy, nhưng đọc trúng trang hỏng có thể lỗi hoặc ra dữ liệu sai.
• Đừng restore đè và đừng chạy lệnh sửa hàng loạt: backup mới chụp sau thời điểm hỏng cũng mang trang hỏng.
• Email hello@embra.cloud kèm operation_id, workspace, environment. Đội Embra tìm bảng bị ảnh hưởng và mốc khôi phục cuối cùng còn sạch.

Khi Embra dừng lại chờ kiểm tra

Ba mã dưới đây chung một nguyên tắc: khi không chắc một bước đã xong hay chưa, Embra cố ý dừng thay vì tự retry. Retry một việc chưa rõ kết quả, như chạy migration hai lần hay chuyển database khi chưa biết trạng thái, có thể làm hỏng data. Đội Embra xác minh trạng thái thật rồi mới mở lại environment.

RECOVERY_REQUIRED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	contact_operator	30	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Một thao tác trên environment (deploy, rollback, restore, bật/tắt app…) kết thúc mà Embra không xác định được kết quả, ví dụ mất kết nối với server giữa chừng. Console hiện “Cần đội Embra hỗ trợ”, trang Tổng quan hiện “Đội Embra cần kiểm tra trước khi bạn deploy tiếp”.

Trạng thái lúc này:

• Embra giữ nguyên traffic như lúc sự cố. Tuỳ thời điểm, app có thể đang chạy bình thường, đang chạy bản mới, hoặc đang dừng (ví dụ sự cố lúc chuyển sang bản restore).
• Environment bị chặn: deploy, build khi push, rollback, restore, bật/tắt app, đổi domain, nhập data đều bị từ chối với ENVIRONMENT_BLOCKED.
• Cron không chạy. Backup định kỳ tạm dừng.

KHÔNG nên:

• Xoá environment. Vẫn xoá được, nhưng xoá luôn database và backup mà đội Embra cần để xác minh và khôi phục.
• Tự chạy SQL để “sửa” schema hoặc data: làm việc xác minh khó hơn.
• Push liên tục hoặc thu hồi secret để “gỡ chặn”: không có tác dụng.

Nên:

1. Bấm “Liên hệ hỗ trợ” trên console, hoặc email hello@embra.cloud kèm mã operation, workspace, environment và giờ.
2. Ghi lại thao tác bạn vừa làm trước khi lỗi xuất hiện.
3. App đang lỗi với người dùng thì ghi rõ trong email để đội Embra ưu tiên.

MIGRATION_UNKNOWN

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
200	Không	contact_operator	30	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Embra mất liên lạc lúc đang chạy migration trên production, nên không biết migration đã áp hay chưa. Console hiện “Cần xác minh dữ liệu”.

Trạng thái lúc này:

• Code cũ vẫn chạy. App mới chưa start, vì Embra chỉ start app mới sau khi migration xong.
• Schema có thể là bản cũ hoặc mới. Mỗi file migration chạy trong transaction riêng, nên một file hoặc đã áp trọn vẹn, hoặc chưa áp gì (trừ file CREATE INDEX CONCURRENTLY, vốn không chạy trong transaction).
• Embra đã chụp snapshot database ngay trước khi chạy migration.
• Environment bị chặn như ở RECOVERY_REQUIRED.

KHÔNG nên:

• Xoá environment hoặc database.
• Sửa, đổi tên hay xoá file migration đang chờ, hoặc thêm migration mới để “chạy lại”.
• Tự chạy lại câu lệnh migration bằng tay.

Nên: email hello@embra.cloud kèm mã operation, workspace, environment và giờ. Đội Embra kiểm tra schema thật, ghi nhận đúng kết quả rồi mở lại environment.

ENVIRONMENT_BLOCKED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	contact_operator	30	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Environment bị chặn sau một sự cố chưa rõ kết quả (RECOVERY_REQUIRED hoặc MIGRATION_UNKNOWN). Mọi thao tác thay đổi bị từ chối tới khi đội Embra kiểm tra xong, kể cả approve plan deploy hay import đang chờ. Plan vẫn giữ trạng thái chờ approve: gỡ chặn xong approve lại được (nếu chưa quá hạn). “Từ chối” plan thì vẫn làm được. Trang Tổng quan hiện “Đội Embra cần kiểm tra trước khi bạn deploy tiếp”, service hiện “Chờ đội Embra kiểm tra”.

Câu lỗi: 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? Không. Sẽ bị từ chối y như cũ tới khi environment được mở.

KHÔNG nên xoá environment. Email hello@embra.cloud kèm mã operation của thao tác lỗi đầu tiên (thao tác có trạng thái “Cần đội Embra hỗ trợ” hoặc “Cần xác minh dữ liệu” ở “Lần deploy”), workspace, environment và giờ.

Câu Database không ở trạng thái sẵn sàng (…). Liên hệ đội Embra (hello@embra.cloud). cũng dùng mã này: database của environment đang lỗi. Xử lý như trên.

Khác

OPERATION_IN_PROGRESS

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	wait	10	embra wait <op_id>

Environment đang có thao tác khác chưa xong (build, deploy, dựng database, restore…), hoặc đang bị xoá. Chờ xong rồi thử lại. Xem tiến độ ở “Lần deploy”.

INVALID_INPUT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
400	Không	fix_input	2	Sửa theo mục này rồi làm lại

Input không hợp lệ: tên sai mẫu, giá trị ngoài khoảng cho phép, thiếu field. Câu lỗi thường nêu field nào sai. Sửa theo câu lỗi rồi làm lại.

Câu hay gặp:

• “Environment đang tạm dừng. Chạy embra env resume trước khi deploy.”: bật lại app trước, rồi deploy.
• “Database đang dừng. Chạy embra db start trước khi fork.”: bật lại database trước.
• Tối đa 100 file migration mỗi plan …, Tổng dung lượng migration vượt 2 MiB.: chia nhỏ, mỗi file tối đa 256 KiB.

NOT_FOUND

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
404	Không	fix_input	1	Sửa theo mục này rồi làm lại

Không tìm thấy thứ bạn yêu cầu (project, environment, domain, token…). Có thể đã bị xoá, hoặc nằm ở workspace khác. Kiểm tên hoặc mã, và kiểm bạn đang ở đúng workspace.

IDEMPOTENCY_CONFLICT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	fix_input	10	Sửa theo mục này rồi làm lại

Request gửi lại dùng cùng Idempotency-Key nhưng nội dung khác lần trước, hoặc request đã chạy và không trả lại giá trị bí mật lần nữa. Gửi request mới với key mới.

FORK_SECRET_IS_PROD

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
409	Không	fix_input	10	Sửa theo mục này rồi làm lại

Giá trị bạn đặt cho fork trùng secret của production. Fork không được dùng key thật. Tạo key test hoặc sandbox ở nhà cung cấp (thanh toán, email…) rồi đặt lại.

RATE_LIMITED

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
429	Có	wait	75	embra wait <op_id>, hoặc chờ rồi thử lại

Gửi quá nhiều request trong thời gian ngắn. Chờ vài giây rồi thử lại. Retry an toàn.

TEMPORARILY_UNAVAILABLE

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
503	Có	wait	75	embra wait <op_id>, hoặc chờ rồi thử lại

Một thành phần của Embra tạm thời không trả lời. Chưa có gì thay đổi. Chờ một lúc rồi thử lại; retry an toàn. Kéo dài thì email hello@embra.cloud.

API_UNREACHABLE

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
— (CLI)	Có	fix_input	1	Kiểm --api/EMBRA_API và mạng, chạy lại

Do CLI hoặc embra mcp báo, không phải máy chủ. Yêu cầu chưa được gửi: sai địa chỉ API (--api, EMBRA_API), máy không có mạng, DNS hoặc TLS lỗi. Chưa có gì thay đổi trên Embra. Kiểm địa chỉ và mạng rồi chạy lại đúng lệnh đó.

WAIT_TIMEOUT

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
— (CLI)	Có	wait	75	embra wait <op_id>, hoặc chờ rồi thử lại

Do CLI hoặc embra mcp báo. Bạn dùng --wait, embra wait hoặc embra_wait, và đã hết --timeout trong khi operation vẫn đang chạy. Không có gì hỏng. Chờ tiếp bằng embra wait <op_id>, đừng chạy lại lệnh tạo operation.

INTERNAL

HTTP	Retry tự động	next_action	Exit code	Lệnh tiếp
500	Không	contact_operator	1	Không có, cố ý. Email hello@embra.cloud kèm operation_id

Lỗi phía Embra. Thử lại một lần. Vẫn lỗi thì email hello@embra.cloud kèm mã operation và giờ.

Mã thoát của CLI

Dùng exit code để script CI biết nên làm gì:

Exit code	Nghĩa
0	Xong
1	Lỗi login, không tìm thấy, không kết nối được (API_UNREACHABLE), hoặc lỗi phía Embra
2	Input sai (INVALID_INPUT, REPO_CONFIG_INVALID, SOURCE_ARCHIVE_INVALID)
10	Thao tác bị từ chối hoặc fail (phần lớn mã lỗi)
20	Đang chờ approve (APPROVAL_REQUIRED, MIGRATION_DATA_LOSS)
30	Cần đội Embra (RECOVERY_REQUIRED, MIGRATION_UNKNOWN, ENVIRONMENT_BLOCKED, tạm ngưng)
75	Tạm thời, thử lại sau (RATE_LIMITED, TEMPORARILY_UNAVAILABLE), hoặc hết thời gian chờ (WAIT_TIMEOUT)