Web Serial および @gurezo/web-serial-rxjs でよくある問題の確認手順と対処です。まだ接続できていない場合は先に クイックスタート の利用条件を確認してください。エラーコード一覧は 概念と設計メモ を参照してください。
症状: 接続ボタンを押しても何も起きない、またはダイアログは開くがデバイスが一覧に出ない。
確認:
connect$() を ユーザー操作（ボタンクリックなど）から呼び出しているか。そうでないとブラウザはダイアログを開きません — クイックスタート – 利用条件。対処: クリックハンドラから接続し、セキュアコンテキスト / ブラウザ対応を直し、ポートを解放してから再度 connect$() を購読してください。
症状: state$ が unsupported のまま、または connect$ が SerialErrorCode.BROWSER_NOT_SUPPORTED で失敗する。
確認:
import { isWebSerialSupported } from '@gurezo/web-serial-rxjs';
if (!isWebSerialSupported()) {
console.error('このブラウザでは Web Serial API を利用できません');
}
対処: 公式サポート対象のデスクトップブラウザ（Chrome 89+、Edge 89+、Opera 75+、Firefox 151+）を使ってください。Safari は現時点で Web Serial API を実装していません。モバイルブラウザは未検証・公式サポート対象外であり、多くの環境では API 自体が無く isWebSerialSupported() が false になります。ブラウザサポートと公式サポート方針、Examples の利用条件、リポジトリ README も参照してください。
症状: navigator.serial が無い、または Examples で insecure-context と表示される。
確認: オリジンは HTTPS、または http://localhost / http://127.0.0.1 である必要があります。LAN IP やホスト名の平文 http:// では Web Serial は露出しません。
対処: HTTPS で配信する、ローカル開発は localhost を使う、または TLS 終端付きのトンネルを使う。詳細: クイックスタート – 利用条件。
症状: connect$() / send$() / disconnect$() / dispose$() を呼んでもダイアログも送信も破棄も起きない。
確認: これらのメソッドは cold な Observable を返します。購読（subscribe）したときだけ実行されます。
// 購読しない限り何も起きない
session.connect$();
// 接続フローが走る
session.connect$().subscribe({
error: (e) => console.error(e),
});
対処: 必ず購読してください（Promise 化する場合も購読が発生する形にする）。send$ / disconnect$ / dispose$ も同様です。クイックスタート を参照。
症状: 送信が無視されたように見える、lines$ に応答が来ない、ターミナル表示が崩れる。
確認:
\r\n を期待します。session.send$(${line}\r\n) や小さな sendLine ヘルパーを使う — 高度な使用方法 – 行送信。lines$。\r による上書きを含むターミナル表示には receive$（または terminalText$）。対処: 送信改行をデバイスに合わせ、受信は用途に応じて lines$ / receive$ を選ぶ。レシピ: 高度な使用方法 – 行フレーミング。
症状: 一覧には出るが open に失敗する、または PORT_OPEN_FAILED などが errors$ に出る。
確認: 別プロセスや別タブがポートを掴んでいる可能性があります。多くの OS では同時に 1 つの opener しか所有できません。
対処: 他のシリアルツールやタブを閉じ、必要なら抜き差ししてからユーザー操作で再接続する。errors$ を確認 — SerialError の確認。
症状: 切断やエラーのあと接続できず、SESSION_DISPOSED や PORT_ALREADY_OPEN になる。
確認:
disconnect$ 後は同一セッションを 'idle'（または 'error' からの回復後）から再利用できます。disconnect$ を購読し、state$ で idle を待ってから再度 connect$()。dispose$ 後はセッションは永久破棄です。新しい createSerialSession() を作り、破棄済みインスタンスは使わない。'connecting' / 'connected' のときに connect$ を呼ぶと PORT_ALREADY_OPEN になります。対処: UI は state$ から駆動する。baud rate 変更や完全破棄では dispose$ のあと新規 session を作る。クイックスタート – 切断 / 破棄 と 高度な使用方法 を参照。
症状: Error.message だけでは失敗の種類が分からない。
確認: errors$ を購読し、error.is(SerialErrorCode.*) で narrowing する。cause 付きコードは error.context.cause を読む。
import { SerialErrorCode } from '@gurezo/web-serial-rxjs';
session.errors$.subscribe((error) => {
if (error.is(SerialErrorCode.OPERATION_CANCELLED)) {
console.info('ポート選択がキャンセルされました');
return;
}
if (error.is(SerialErrorCode.READ_FAILED)) {
console.error('読み取り失敗:', error.context.cause);
return;
}
console.error(error.code, error.message, error.context);
});
connect$().subscribe({ error }) や send$().subscribe({ error }) の error も扱い、同じ SerialError が errors$ に多重配信されます。
対処: コードで分岐する。一覧は SerialError / SerialErrorCode。
解決できない場合は、使い方の質問は GitHub Discussions、バグは 日本語 / 英語 の Issue フォームへ。
次を含めてください。
@gurezo/web-serial-rxjs と rxjs のバージョンSerialSessionStatus / SerialErrorCode（あれば context）