Amazon Q インストール時エラー集

概要

Amazon Q（AWS CLI の AI アシスタント）のインストール後に q doctor コマンドを実行した際に発生する３つのエラーとその解消方法について説明します。

事例①「bashrc ファイル・profile ファイル・PATHエラー」

内容

bash

✘ bash ~/.bashrc integration check: /home/ubuntu/.bashrc does not source pre integration

  Run q integrations install dotfiles to reinstall shell integrations for bash
Attempting to fix automatically...
Re-running check...

✔ bash ~/.bashrc integration check
✘ bash ~/.profile integration check: /home/ubuntu/.profile does not source pre integration

  Run q integrations install dotfiles to reinstall shell integrations for bash
Attempting to fix automatically...
Re-running check...

✔ bash ~/.profile integration check
✘ PATH contains ~/.local/bin: Path does not contain ~/.local/bin


✘ Doctor found errors. Please fix them and try again.

If you are not sure how to fix it, please open an issue with q issue to let us know!

原因

bash ~/.bashrc integration check:

~/.bashrc ファイル内で、Q のための設定ファイルが読み込まれていない (does not source pre integration) ことを示しています。bashrc は、Bashシェルが起動するたびに実行される設定ファイルで、ここに Q の設定を記述しておく必要があります。

bash ~/.profile integration check:

同様に、~/.profile ファイル内で Amazon Q の設定が読み込まれていないことを示しています。profile ファイルはログイン時に一度だけ実行される設定ファイルで、こちらも Amazon Q の設定を記述しておく必要があります。

PATH contains ~/.local/bin:

システムの実行可能ファイルを探すためのディレクトリ一覧 (PATH 環境変数) に、~/.local/bin が含まれていないことを示しています。~/.local/bin は、ユーザーごとのプログラムをインストールする際に使われる一般的なディレクトリです。Amazon Q がここにインストールされている場合、このディレクトリを PATH に追加しないと、q コマンドが認識されません。

解消方法

ステップ1: シェル統合の再インストール

bash

bashq integrations install dotfiles

実行すると~/.bashrc と ~/.profile にAmazon Qの統合設定が自動的に追加されます。
（必要な環境変数とパス設定が構成されます。）

ステップ2: 設定ファイルの再読み込み

bash

bashsource ~/.bashrc
source ~/.profile

更新された設定ファイルを現在のシェルセッションに適用します。
PATH環境変数を含む全ての変更を有効化します。

ステップ3: 修復確認

bash

q doctor

SSHセッションを一度切断した後に再接続し、全てのチェックが通ることを確認します。

事例②「SSHD config エラー」

内容

bash

✘ sshd config: SSHD config is not set up correctly

  The /etc/ssh/sshd_config file needs to have the following line:
    AcceptEnv Q_SET_PARENT
    AllowStreamLocalForwarding yes
  
  If your sshd_config is already configured correctly then:
    1. Restart sshd, if using systemd: sudo systemctl restart sshd
    2. Disconnect from the remote host
    3. Run q integrations install ssh on the local machine
    4. Reconnect to the remote host and run q doctor again
  
  See https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-autocomplete-ssh.html for more info

✘ Doctor found errors. Please fix them and try again.

If you are not sure how to fix it, please open an issue with q issue to let us know!

原因

SSHデーモンの設定ファイルである/etc/ssh/sshd_configに、Amazon Qがリモート接続で正しく動作するために必要な設定が欠けていることを意味します。

解消方法

ステップ1: /etc/ssh/sshd_configファイルの編集

bash

sudo nano /etc/ssh/sshd_config

ステップ2: 設定の追加

以下の２行をsshd_configファイルの末尾に追加します。

AcceptEnv Q_SET_PARENT
AllowStreamLocalForwarding yes

• AcceptEnv Q_SET_PARENT: SSHセッションでクライアント側からQ_SET_PARENTという環境変数を受け入れることを許可します。Amazon Qがローカルマシンとリモートマシン間で連携するために必要です。

• AllowStreamLocalForwarding yes: SSHセッションでストリームローカルフォワーディングを許可します。これにより、Amazon Qのコマンドラインツールがローカルのバックエンドサービスと通信できるようになります。

ステップ3: 修復確認

bash

q doctor

SSHセッションを一度切断した後に再接続し、全てのチェックが通ることを確認します。

事例③「ターミナル統合エラー」

内容

bash

✘ Amazon Q terminal integrations: qterm is not running in this terminal, please try restarting your terminal

  Q_TERM=


✘ Doctor found errors. Please fix them and try again.

If you are not sure how to fix it, please open an issue with q issue to let us know!

原因

Amazon Qのターミナル拡張機能（qterm）が、現在開いているターミナルプロセスで実行されていないことを意味します。これにより、Qのオートコンプリートなどの機能が利用できません。

エラーメッセージにあるQ_TERM=は、Q_TERMという環境変数が設定されていないことを示しています。通常、この環境変数はターミナル起動時にQのスクリプトによって自動的に設定されます。

解消方法

ステップ1: 再起動

再起動してください。
ターミナルを閉じて再度開き直すことで、起動スクリプト（~/.bashrcなど）が再実行されます。

ステップ2: 修復確認

bash

q doctor

SSHセッションを一度切断した後に再接続し、全てのチェックが通ることを確認します。

まとめ

Amazon Q の q doctor コマンドで発生する代表的な３つのエラー（bashrc・profile・PATH、SSHD config、ターミナル統合）の解決方法を紹介しました。各エラーには明確な原因と対処法があり、手順通りに実行すれば確実に解決できます。エラー解決後はSSHセッションの再接続と q doctor での確認を忘れずに行ってください。