Troubleshooting

Check first

Update the app to the latest version. Many problems have been fixed in newer versions. For features used together with a phone or another PC, the connected PC must also be on the latest version.
Check the exact error message. The app shows different guidance depending on the cause.

Installation and updates

Windows shows a SmartScreen warning

This warning appears because the Windows installers do not have an Authenticode code signature yet. Make sure the file came from the official download page, then click More info → Run anyway. For details, see Install and first run.

The Portable version does not update itself

Windows Portable does not support automatic installation from inside the app. Download the new file from the download page and replace the old one. If you need automatic updates, use the Setup version.

Cannot connect to the update server

If the app cannot reach the update address, it opens the release page in your default browser. You can download the installer directly from there. Updates do not require an account or access token.

No update notifications appear

If you chose 나중에 (Later), you will not be notified again for 4 hours during that session.
If you chose 이번 버전 건너뛰기 (Skip this version), you will not be notified about that version automatically.
If you check manually with the download icon at the top, postponed and skipped versions are shown again.

Update installation fails

The reason for the failure is shown in the update window and the restart confirmation dialog.

macOS: If an error or a 120-second timeout occurs during installation verification, you can try again.
Linux .deb: An administrator authentication dialog should appear during installation. If it does not appear within 3 minutes, installation stops and the app shows a command to install directly from a terminal. The guidance distinguishes between canceling the authentication dialog and failing to obtain permission.
Linux, when the app was launched from a sandboxed shell: Privilege escalation may be blocked by the NoNewPrivs restriction. The app opens an authentication dialog through the user systemd instance, and if that still fails, explains how to install with sudo from a terminal outside the app.

Phone connection and QR codes

Cannot click 「연결 QR 만들기」 (Create connection QR)

A QR code can be created only after the PC is connected to the relay server. Check under 환경 설정 › 휴대폰 (Settings › Phone) that 휴대폰 연결 켜기 (Turn on phone connection) is on and the status is connected.

Cannot turn on phone connection

If the PC cannot use the operating system's secure storage, phone connection cannot be turned on. Data is not stored in plain text as a substitute. On Linux, turn on a keyring such as Secret Service and restart the app.

The QR code is reported as expired or already used

A QR code is valid for 5 minutes only and can be used only once. Create a new QR code on the PC and connect again.

「연결 시도가 너무 잦습니다」 (Too many connection attempts) appears

The PC briefly blocks (for about 1 minute) connections that failed authentication, through the relay server. Wait about 1 minute, then try again with a new QR code.

「연결이 해제되었습니다」 (Disconnected) appears

This happens when the PC disconnected this phone or a new desktop identity was created. Create a new QR code on the PC and connect again. If you connected with a Google account, allow it again in the PC's approval dialog.

The PC is reported as turned off

Check that the PC is on and Agent Switchboard is running. The connection is restored automatically when the PC comes back on.

The Android app only shows 「네트워크 연결을 확인하세요」 (Check your network connection)

Android apps signed with the release key (0.6.0 or later) accept Google account connections only from PC version 0.65.2 or later. Update the PC app.

「Google 계정을 확인하지 못했습니다」 (Could not verify Google account) appears

If the PC's clock is behind, verification of the Google sign-in proof can fail. PC version 0.65.3 fixed the case where the clock is slightly behind. Update the PC app and keep the operating system's automatic time sync turned on.

The PC's Google sign-in has expired. Click Google 다시 로그인 (Sign in to Google again) under Settings › Phone. Until you sign in again, new connections from other devices cannot be accepted.

Cannot install the Android app again

If you previously installed an APK built with a different signature, the new APK cannot be installed over it. Uninstall the existing app, install the new APK, and then connect to your PC and sign in with Google again.

The PC list is empty after the web app address changed

The phone web app is served at https://app.switchboard.twentyoz.kr. Connection information used at the old address is not carried over to the new address. Connect again with a QR code, or if you were using a Google account, sign in again to load your PC list.

Keys and authentication

「저장 후 적용」 (Save and apply) is disabled (Linux)

API keys cannot be saved on a PC that cannot use the OS secure storage (keyring). The reason is shown above the button. Turn on a keyring and restart the app.

The selected model is not applied

During the connection test and when applying, the app checks whether the selected model can actually be used. If it cannot, the change is not applied. Choose a usable model from the list again.

The CLI reports a "credential is not configured" error

This can happen when a CLI is launched with an outdated launch profile after the folder's connection changed. Apply that connection again in the tool settings and start the CLI anew. If the folder has Codex settings but its folder connection profile has disappeared, the app recreates the profile from the saved settings.

"SECURE_STORAGE_BOOTSTRAP_FAILED" keeps appearing

Make sure Agent Switchboard and all related processes have exited.
If a forced exit during initialization left only the .secure-storage-bootstrap.lock lock file behind, back that file up separately, delete it, and run the app again.
Do not delete or change the Local State file or the credentials folder. Keep the originals as they are and contact us.

The app says it could not confirm support for the reasoning effort

A reasoning effort whose support has not been confirmed is sent as the tool's default, and a notice is left. If this message prevented you from starting a chat in an earlier version, update the app.

This was caused by the user's PowerShell startup profile blocking the sign-in command. Since 0.61.2, the authentication window skips the startup profile. Update the app.

When contacting us

When reporting a security-related problem, do not attach API keys, OAuth tokens, authentication files, or entire settings files. Send only the connection address, operating system, app version, steps to reproduce, and the error message with sensitive values masked. Contact us at hello@twentyoz.kr.