کاتالوگ خطاها#

خطاهای الامر کدهای پایدار ALAMR_* دارند. اتوماسیون را بر اساس کد و فیلدهای ساختاریافته بساز، هرگز بر اساس متن. فهرست هستهٔ ماشین‌خوان در /agent/v2/errors/index.json سرو می‌شود؛ عیب‌یابی مجموعهٔ عملیاتی وسیع‌تر را با راهنمای مبتنی‌برعلامت پوشش می‌دهد.

چطور یک خطا را بخوانیم#

هر نتیجهٔ JSON در CLI یک envelope مشترک دارد: ok، code نمادین، exitCode فرایند، diagnostics ساختاریافته، nextActions و artifacts. نخستین خطای ساختاریافته را حفظ کن؛ خطاهای بعدی معمولاً پیامد آن‌اند. exit codeهای فرایند پایدارند: 0 موفقیت، 1 شکست اعتبارسنجی یا عملیات، 2 استفادهٔ نامعتبر، 3 شکست احراز هویت یا مجوز، 4 شکست شبکه، 5 تعارض وضعیت.

کدهای bootstrap و Release Set#

<!-- sources: platform/developer-portal/lib/platform-release.ts, packages/cli/src -->

Code	Retryable	معنی	اقدام بعدی
ALAMR_PLATFORM_RELEASE_UNAVAILABLE	بله	هیچ Release Set ترفیع‌یافته‌ای در bootstrap عمومی در دسترس نیست.	fail-closed؛ /status را دنبال کن و پس از promotion دوباره تلاش کن.
ALAMR_RELEASE_VERIFICATION_UNAVAILABLE	بله	هیچ Release Set تأییدشده‌ای در مسیر verification نیست.	منتظر تکمیل release verification بمان و از ID دقیق Release Set استفاده کن.

کدهای احراز هویت و حساب#

<!-- sources: packages/cli/src -->

Code	Retryable	معنی	اقدام بعدی
ALAMR_AUTH_REQUIRED	خیر	credential غایب، منقضی یا ناکافی (exit 3).	با alamr login وارد شو یا AL_AMR_TOKEN محدودبه‌scope بده.
ALAMR_AUTHORIZATION_DENIED	خیر	احرازهویت‌شده، ولی action مجاز نیست.	نقش Project و scope توکن را بررسی کن.
ALAMR_LOGIN_APPROVAL_REQUIRED	خیر	handoff ورود device ساخته شده؛ یک انسان باید تأییدش کند.	انسان verificationUriComplete را باز می‌کند و userCode را تأیید می‌کند.
ALAMR_LOGIN_APPROVAL_PENDING	بله	انسان هنوز handoff دستگاه را تأیید نکرده است.	با بازهٔ برگردانده‌شده retry کن و سپس resume کن.

کدهای شبکه#

<!-- sources: packages/cli/src -->

Code	Retryable	معنی	اقدام بعدی
ALAMR_NETWORK_ERROR	بله	مشکل DNS، TLS، پروکسی، فایروال، timeout یا قطعی Registry (exit 4).	URL پیکربندی‌شدهٔ Registry و مسیر شبکه را بررسی کن.

کدهای استفاده و تعارض#

<!-- sources: packages/cli/src -->

Code	Retryable	معنی	اقدام بعدی
ALAMR_ERROR	خیر	شکست اعتبارسنجی یا عملیات (exit 1).	diagnostics ساختاریافته را بخوان و علت گزارش‌شده را رفع کن.
ALAMR_USAGE	خیر	آرگومان‌های نامعتبر یا گزینه‌های پشتیبانی‌نشده (exit 2).	alamr --help را اجرا کن و فراخوانی را اصلاح کن.
ALAMR_CONFLICT	خیر	تعارض وضعیت در Registry (exit 5).	با alamr status وضعیت را تازه کن؛ هرگز تعارض را به retry تبدیل نکن.

کدهای gate در workflow#

<!-- sources: packages/cli/src/commands/workflow.ts, packages/cli/src/workflow-execution.ts -->

Code	Retryable	معنی	اقدام بعدی
ALAMR_WORKFLOW_APPROVAL_REQUIRED	خیر	workflow به یک human gate اعلام‌شده رسیده است.	actor، target، snapshot و evidence digest را به انسان ارائه بده.
ALAMR_WORKFLOW_APPROVED	خیر	تصمیم gate ثبت شده است (اطلاعاتی).	workflow را ادامه بده.
ALAMR_WORKFLOW_IDEMPOTENT_REPLAY	خیر	یک workflow تکمیل‌شده دوباره پخش شده (اطلاعاتی).	mutation را تکرار نکن؛ از نتیجهٔ ثبت‌شده استفاده کن.

کدهای اثبات Journey#

Journeyهای نویسندگی وقتی یک اثبات لازم غایب باشد با این کدهای completion assertion به‌صورت fail-closed متوقف می‌شوند. remediation همیشه این است: قدم غایب را برای revision، release یا artifact دقیق انجام بده — هرگز evidence را ویرایش نکن.

<!-- sources: platform/developer-portal/lib/authoring-journey-builder-v2.ts -->

Code	معنی
ALAMR_PUBLICATION_NOT_PUBLISHED	target در وضعیت منتشرشده‌ای که Journey انتظار دارد نیست.
ALAMR_REQUESTED_BEHAVIOR_NOT_PROVEN	رفتار اعلام‌شده برای Journey اثبات نشده است.
ALAMR_ENVIRONMENT_CONSUMER_ENTRY_MISSING	ورود مصرف‌کنندهٔ مستقل به Environment منتشرشده وجود ندارد.
ALAMR_HUB_VISITOR_ENTRY_MISSING	پس از جای‌گذاری، بازدید واقعی از Hub وجود ندارد.
ALAMR_HUB_PLACEMENT_NOT_CLEARED	جای‌گذاری Hub پس از اثبات پاک نشده است.
ALAMR_APP_LAUNCH_MISSING	revision منتشرشدهٔ App در یک Runtime اجرا نشده است.
ALAMR_APP_WORKSPACE_MODE_MISSING	حالت Workspace اعلام‌شده اثبات نشده است.
ALAMR_APP_CONSUMER_PRINCIPAL_NOT_INDEPENDENT	اثبات مصرف‌کنندهٔ App با principal غیرمستقل انجام شده است.
ALAMR_PLUGIN_CONSUMER_INSTALL_MISSING	نسخهٔ دقیق Plugin در یک Environment مصرف‌کننده نصب نشده است.
ALAMR_PLUGIN_CONSUMER_ENVIRONMENT_PUBLICATION_MISSING	خود Environment مصرف‌کننده منتشر نشده است.
ALAMR_PLUGIN_CONSUMER_PRINCIPAL_NOT_INDEPENDENT	اثبات مصرف‌کنندهٔ Plugin با principal غیرمستقل انجام شده است.
ALAMR_PLUGIN_FRONTEND_ACTIVATION_MISSING	رفتار frontend پلاگین در مصرف‌کننده فعال نشده است.
ALAMR_PLUGIN_BACKEND_ACTION_MISSING	action مربوط به backend پلاگین در مصرف‌کننده اعمال نشده است.

همچنین ببین#

• عیب‌یابی — فهرست عملیاتی مبتنی‌برعلامت با مجموعهٔ وسیع‌تر کدها.
• توسعهٔ AI-native — ترتیب کشف و قرارداد Context Pack که عامل‌ها دنبال می‌کنند.
• بازیابی و rollback — checkpointها، resume و مدیریت rejection.
• مرجع CLI — سطح دستورها و envelope مربوط به JSON.