Вирішення проблем

Поширені рішення для проблем встановлення, автентифікації та роботи з RAPS.

Проблеми встановлення

Команда не знайдена — переконайтеся, що raps додано до вашого PATH. На Windows перевідкрийте термінал після встановлення через Scoop/PowerShell; на macOS/Linux переконайтеся, що /usr/local/bin або обрана вами директорія встановлення є у PATH.
Застарілий бінарний файл — виконайте raps --version та перевстановіть зі сторінки релізів або через ваш менеджер пакетів, якщо версія нижча за вказану в документації.
Відсутні SSL-сертифікати — контейнерні образи або мінімальні дистрибутиви можуть не мати пакетів кореневих сертифікатів. Встановіть ca-certificates (Debian/Ubuntu) або ca-certificates-utils (Arch), щоб забезпечити роботу OAuth-трафіку.

Проблеми автентифікації

Невірні облікові дані — повторно скопіюйте APS_CLIENT_ID та APS_CLIENT_SECRET з APS Developer Portal і виконайте raps auth test. Зайві пробіли з буфера обміну або переплутані значення — найпоширеніші причини відповідей 401.
Тайм-аут device code — якщо SSO-підтвердження займає надто багато часу, використайте raps auth login --force-pkce, щоб ініціювати інтерактивний потік PKCE у браузері замість циклу device code.
Кілька профілів — raps config profile list показує, який профіль активний. Використайте raps config profile use staging (або іншу назву) перед виконанням команд, щоб не змішувати токени тестового та робочого середовищ.

Авторизація та дозволи

403 Forbidden — переконайтеся, що застосунок APS має правильні області доступу для API, до якого ви звертаєтесь. Для операцій з бакетами та об’єктами зазвичай потрібні області data:read, data:write та bucket:create.
Доступ до ACC/BIM 360 — переконайтеся, що застосунок APS додано до облікового запису BIM 360 з відповідною роллю. Без затвердження адміністратором запити до папок або issues повертатимуть порожні списки.
Невідповідність регіонів — перегляньте свої бакети за допомогою raps bucket list --region us або --region emea, щоб переконатися, що завантаження та трансляції відбуваються у правильному регіоні.

Безпека та зберігання токенів (v3.7.0+)

Помилки доступу до сховища ключів — якщо ви отримуєте помилки “access denied” зі сховищем ключів, виконайте raps config set use_keychain false, щоб тимчасово перейти на файлове сховище під час діагностики проблем зі сховищем ключів.
Міграція токенів — при оновленні з v3.6.x або раніших версій виконайте raps config migrate-tokens, щоб перемістити наявні токени з файлового сховища до безпечного сховища ключів.
Безголові середовища — у контейнерах Docker або CI-середовищах без підтримки сховища ключів використовуйте змінну середовища RAPS_USE_FILE_STORAGE=true для увімкнення файлового зберігання токенів.

Надійність робочих процесів

Великі завантаження — перейдіть на багаточастинне завантаження за допомогою raps object upload my-bucket model.rvt --multipart --chunk-size 16MB, щоб уникнути тайм-аутів на повільних мережах.
Трансляція застрягла у стані pending — використайте raps translate status $URN --wait --interval 10 для опитування та виявлення помилок. Якщо статус залишається pending, повторіть із правильним прапорцем формату (наприклад, --format svf2).
Нестабільність CI/CD — увімкніть детальні логи за допомогою RAPS_LOG=debug у вашому робочому процесі та перевірте HTTP-коди, що допускають повторну спробу. Стандартизовані коди завершення (raps --help exit-codes) допомагають швидко виявляти помилки у конвеєрах.

Відновлення пакетного завантаження (v4.5)

Розташування файлу стану — стан пакетного завантаження зберігається у ~/.config/raps/batch-state.json (Linux/macOS) або %APPDATA%\raps\batch-state.json (Windows).
Застарілий стан — якщо --resume завершується помилкою “no matching state”, видаліть файл стану вручну та почніть заново.
Часткові помилки — коли деякі файли не вдалося завантажити, стан зберігається автоматично. Повторіть запуск з --resume, щоб повторити спробу лише для файлів з помилками.
Інший бакет — відновлення працює лише для того самого бакета та набору файлів. Зміна бакета призначення потребує нового завантаження.

Отримання допомоги

Якщо проблеми зберігаються, створіть issue на GitHub із зазначенням вашої ОС, версії RAPS та мінімальної команди, що відтворює проблему. Перед публікацією логів обов’язково видаліть з них секретні дані та облікові дані.