Справочник
Коды ошибок
Коды отказов платформы: когда возникают и что делать.
Ошибка платформы приходит в форме { "error": "…", "code": "…", "hint": "…" }. Ветвиться
можно только по code и limit.code: тексты error и hint меняются, коды нет. Тексты
английские, их читает агент.
Доступ и ключи
Заголовок раздела «Доступ и ключи»| Код | Когда | Что делать |
|---|---|---|
unauthorized |
ключа нет или он недействителен | xflow login; в CI проверить XFLOW_TOKEN |
forbidden |
у ключа нет нужного права, или доступ к проекту только на просмотр | право включает владелец ключа в настройках платформы, уровень «Редактирование» выдают в окне «Пригласить» проекта |
not_found |
проекта, приложения или функции нет, либо проект вам закрыт | проверить id; ключ мог быть от другой организации: xflow org |
invalid_request |
запрос неверен; текст называет, что именно | исправить по hint |
invalid_request |
на платформе ревизия новее той, от которой вы работали | xflow pull --into ./server-copy, слить изменения в git, повторить |
invalid_request |
переменная уровня организации, а часть её проектов вам закрыта | xflow env set … --scope project или попросить владельца организации |
confirm_required |
действие необратимо и нужно явное согласие | повторить с согласием: --allow-removals, --yes |
conflict |
состояние успело измениться: имя занято, идёт перенос базы | прочитать текст и повторить |
rate_limited |
слишком много запросов с ключа или адреса | подождать столько, сколько в Retry-After |
outdated_cli |
версия CLI ниже минимальной | xflow update, до этого ничего не заработает |
internal |
сбой на стороне платформы | повторить позже |
Доступ к проектам и права ключа: Участники и доступ, Подключение агента.
Сборка и проверка
Заголовок раздела «Сборка и проверка»Отказ проверки приходит списком issues, у каждого нарушения код, файл и строки. Сборка не
начинается, попытка ничего не стоит. Правила: Проверка перед сборкой.
| Код | Когда | Что делать |
|---|---|---|
no-package-json, bad-package-json, no-build-script |
нет package.json, он не читается или в нём нет скрипта сборки |
вернуть package.json и скрипт из build.command |
not-vite, ssr-framework, forbidden-directory |
не Vite или серверный фреймворк | приложение это Vite SPA, код в src/ |
no-index-html, no-entry-point |
нет index.html или src/main.tsx (.ts, .jsx, .js) |
вернуть точку входа шаблона |
bad-build-dir |
build.dir указывает за пределы папки |
путь внутри папки приложения: xflow.json |
bad-file-name |
имя файла не латиницей | переименовать: латиница, цифры, пробел и . - _ ~ |
secret-in-source |
в исходниках ключ или токен | убрать в переменные функции |
server-only-api |
во фронтенде fs, http, express и подобные |
серверная часть живёт в функциях |
hardcoded-function-url |
адрес функции вписан в код | звать через xflow.functions.invoke |
no-alert, no-confirm, no-prompt, no-console-log |
системные окна или console.log вне src/components/ui и blocks |
диалоги шаблона; console.error разрешён, но в логи не попадает |
missing-provider |
библиотеке нужен провайдер, а он не подключён | подключить провайдер, иначе белый экран |
missing-ui-component |
импорт компонента из @/components/ui, которого нет |
вернуть компонент или убрать импорт |
platform-file-changed, platform-file-removed, template-wiring-broken |
изменён или удалён файл платформы, сломана проводка шаблона | вернуть оригинал командой из текста отказа: Шаблон |
theme-token-removed, theme-token-unmapped |
удалены токены темы, которыми красят компоненты шаблона | менять значения, а не имена, или удалить и эти компоненты |
functions-in-app |
функция лежит в папке приложения | перенести в functions/<имя>/ корня, выкатить xflow deploy functions |
no-xflow-json, bad-xflow-json |
нет xflow.json в корне или он неверен |
xflow link <id>; поправить по тексту |
bad-function-name |
имя функции не по правилам | строчная латиница, цифры, дефис, до 41 символа |
binding-without-function |
у имени в functions нет папки functions/<имя>/ с index.ts |
добавить функцию или убрать запись |
unknown-caller |
зовущий не приложение этого проекта | указать папку приложения из apps/ |
env-name-not-literal |
имя переменной собрано выражением | писать process.env.ИМЯ буквально |
unknown-min-role |
minRole называет роль, которой нет |
роль из шкалы платформы: Функции |
Пометки сборку не останавливают, но до слова «готово» их исправляют: default-title
(заголовок из шаблона), default-icon (нет иконки), access-export-ignored (exports.access
ничего не значит, зовущие задаются в xflow.json).
| Код | Когда | Что делать |
|---|---|---|
invalid_request |
миграция удаляет данные без --allow-destructive, или изменён уже применённый файл |
для удаления флаг и право на ключе; правку писать новой миграцией |
forbidden |
у ключа нет права удалять данные или переносить базу | право включает владелец ключа |
forbidden, limit.code: db_write_locked |
объём данных вышел за лимит тарифа, запись в базу выключена | удалить лишние строки: запись вернётся в течение часа; или поднять тариф |
Подробнее: База данных.
Функции
Заголовок раздела «Функции»Отказ при вызове функции приходит в поле reason ответа, в коде приложения это code у XFlowError.
| Код | Статус | Когда | Что делать |
|---|---|---|---|
not_bound |
404 | приложение не указано в callers функции |
добавить папку в xflow.json, xflow deploy functions |
not_found |
404 | функция не выкачена | xflow deploy functions |
login_required, invalid_credential |
401 | посетитель не вошёл или вход устарел | войти заново |
no_access |
403 | у человека нет доступа к приложению | доступ даёт человек: Участники и доступ |
role_too_low |
403 | роль ниже minRole функции |
роль выше или другой порог |
functions_stopped |
403 | функции организации остановлены | см. «Тариф» ниже, код тут не поможет |
bad_min_role |
500 | minRole с неизвестной ролью |
исправить minRole в коде функции |
rate_limited |
429 | слишком много вызовов сразу | вызывать пачками, не все элементы списка параллельно |
unavailable |
503 | платформа не смогла проверить вызов | повторить позже |
Падения самого кода смотрят в xflow functions logs <имя>.
Отказ по тарифу приходит как forbidden с полем limit: { "code": "limit_apps", "used": 1, "limit": 1 }.
Повтор, переименование и правка кода не помогают: лимит снимает владелец организации.
Лимиты и занятое: xflow whoami. Подробнее: Тариф.
limit.code |
Когда | Что делать |
|---|---|---|
limit_apps, limit_functions, limit_pages, limit_connections |
кончились приложения, функции, страницы или активные подключения | удалить ненужное, отключить неиспользуемое подключение или поднять тариф |
limit_projects |
100 проектов в организации | удалить ненужные проекты |
limit_seats |
кончились места для людей, считая приглашения | поднять тариф |
limit_builds |
кончились сборки месяца | ждать даты обнуления из текста или поднять тариф |
limit_builds_concurrent |
идёт максимум сборок одновременно | дождаться их и повторить |
plan_no_schedules, limit_schedules, limit_schedule_interval |
расписаний нет на тарифе, кончились или запуск чаще разрешённого | реже запускать или поднять тариф; cron тут ни при чём |
db_write_locked |
база больше лимита | см. «База» выше |
functions_stopped |
кончились минуты функций или подписка не оплачена | оплатить или перейти на тариф выше, функции вернутся сразу |
subscription_blocked |
организация заморожена за неоплату: отказ на всё, кроме xflow whoami |
владелец оплачивает счёт в настройках организации |
billing_unavailable |
платформа не смогла проверить тариф | повторить позже |
Загрузка файлов из кода функции отвечает своими кодами: Файлы.
| Код | Когда | Что делать |
|---|---|---|
quota_exceeded |
хранилище организации заполнено | удалить ненужные файлы или поднять тариф |
file_too_large |
файл больше 200 МБ | уменьшить файл |
duplicate_name |
имя в этой папке занято | overwrite: true заменяет файл, адрес остаётся |
forbidden_type |
страницы, скрипты, исполняемые файлы | хранилище только для ресурсов приложения |
not_uploaded |
подтверждение до конца загрузки | подтверждать после завершения PUT |
invalid_name |
недопустимое имя файла | переименовать |