インポート・連携でハマりやすいポイント
インポート・連携でハマりやすいポイント
外部サービスからのナレッジ取り込みや OAuth 連携で、仕様を知らないと困りやすいポイント を症状別にまとめました。まずここを確認してください。
基本操作は「ナレッジ一覧とインポート」、アカウント連携は「アカウント設定」（No.3.3）を参照。
Qiita インポート
⚠ 記事に iknow タグが必要（最重要）
インポートモーダルの Qiita タブに表示されるのは、自分の記事のうちタグに iknow が付いているものだけ です。
| 症状 |
原因と対処 |
| 「記事が見つかりませんでした」と出る |
取り込みたい記事に iknow タグが付いていない。Qiita 側で記事を編集し、タグ iknow を追加してから再度モーダルを開く |
| 記事はあるのに一部だけ見えない |
iknow タグの有無でフィルタ されている。表示したい記事すべてに iknow を付ける |
| 検索しても「一致する記事がありません」 |
一覧に載っている記事の中でのタイトル検索。先に iknow タグで記事が一覧に出ているか確認 |
手順の例
- Qiita で取り込みたい記事を開く
- 記事のタグに
iknow を追加して保存
- iknow.dev のナレッジ一覧 →「インポート」→ Qiita タブを開き直す
- 記事が一覧に出たら「インポート」または複数選択して一括取り込み
iknow は 大文字小文字を区別 します。タグ名は正確に iknow である必要があります。
Qiita 連携が切れている
| 症状 |
対処 |
| モーダル下部に「ログインしてください。」+ ログインボタン |
アカウント設定の「外部サービス連携」で Qiita を連携し直す。または表示されたログインボタンから再認可 |
| Qiita タブ自体が出ない |
サーバー側で Qiita OAuth が未設定の可能性あり（運営者向け）。利用者はサポートへ |
Qiita とアカウント統合
- Qiita はメールアドレスを返さないため、別プロバイダで作ったアカウントに自動統合されません。
- 既存の iknow.dev アカウントに Qiita を紐づけたい場合は、先にそのアカウントでログインしてから アカウント設定で Qiita を連携してください。
再インポート・ローカル編集
- 既に取り込んだ記事をナレッジエディターで編集したあと再インポートすると、ローカル編集が上書き されます（「ローカル編集あり」バッジ付き）。意図しない上書きに注意。
- インポートモーダル経由では確認ダイアログなしで
force 上書きされます。
GitHub インポート
| 症状 |
原因と対処 |
| タブが出ない / ログインを求められる |
GitHub 連携 がアカウント設定で未完了、または OAuth 期限切れ → 連携し直す |
| ファイルが一覧に出ない |
対応形式は .md / .txt / .html / .xml / .csv / .json のみ。.xlsx / .zip は GitHub タブでは不可（ファイルアップロードを使う） |
| 「アップデート（要確認）」と表示 |
ナレッジをローカル編集済み。再同期すると GitHub 側の内容で上書き（GitHub への push はしない） |
Google スプレッドシート
| 症状 |
原因と対処 |
| URL を貼っても取り込めない |
Google は URL 手入力非対応。「Google ドライブから選択」ボタンで Google Picker からスプレッドシートを選ぶ |
| Picker が開かない |
ポップアップブロック を解除。モーダルを開いてから少し待って再クリック（事前ロードのため） |
| 再同期時にアクセス権エラー |
操作中のユーザーがファイルのアクセス権を失っている → 確認ダイアログから Picker で再選択 して権限を付与 |
| Google 連携が未設定 |
アカウント設定で Google を連携 |
Microsoft Excel / SharePoint（オンプレミスのみ）
iknow.dev（SaaS）では Microsoft 連携は一切利用できません。 この節はオンプレミス導入向けです。SaaS 利用者は .xlsx のファイルアップロードを使ってください。
| 症状 |
対処 |
| タブが出ない / SaaS で使いたい |
SaaS では非対応。Microsoft OAuth はオンプレで .env 設定が必要 |
| 取り込めない（オンプレ） |
Microsoft 連携 が必要。共有 URL を入力し、ドメインから自動判別 |
| テナントで管理者同意が必要 |
組織アカウントでは IT 管理者の同意が必要な場合あり |
ファイルアップロード
| 症状 |
原因と対処 |
.pdf / .docx / .pptx が拒否される |
非対応形式（仕様どおり）。Markdown 等に変換してから .md でアップロード |
| ドロップしても反応しない |
ナレッジ一覧 でドロップ（ナレッジエディターでは不可） |
| 1 件が複数ナレッジに分かれた |
約 80,000 トークン超 で自動分割。タイトル末尾 (1/3) 等が付く |
.xlsx が複数ナレッジになる |
シートごとに 1 ナレッジ（仕様どおり） |
Web URL インポート
| 症状 |
原因と対処 |
.xlsx / .zip / .pdf の URL が拒否 |
Web タブでは HTML / RSS / .csv / .md / .txt / .json のみ。.xlsx はファイルアップロード経由 |
| 同じ URL を再取り込みしたい |
1 URL = 1 ナレッジ で upsert。ローカル編集があると上書き確認が出る |
MCP（Cursor / Claude）連携
| 症状 |
原因と対処 |
| MCP 登録ボタンが見つからない |
アカウント設定の「エージェント連携」セクションの「Cursorへインストール」「Claudeへインストール」から登録（ナレッジ一覧には MCP 登録ボタンはありません） |
| Client Secret を紛失 |
再表示不可。古いクライアントを削除し新規発行 |
| 書き込みが 403 |
オーナー権限 が必要。メンバーは読取のみ |
インポート全般
| 症状 |
対処 |
| 進捗がわからない |
ヘッダー右上アバターの 円形プログレス を確認（秒間 1 回更新） |
| 失敗件数がある |
プログレス完了後に 失敗・スキップの詳細 を確認 |
| オーナーでないとインポートできない |
オーナーのみ インポート可能。メンバーは閲覧・ダウンロードのみ |
| 見出しのリンクが消えた |
インポート時に見出し内の インライン Markdown（リンク等）はプレーンテキスト化 される（仕様） |
| 保存がコンテンツポリシーでブロック |
No.8.6 を参照（モデレーション enforce 時） |
409 version_conflict |
別タブ・MCP と同時編集 → No.5.2 の楽観ロック節 |
クイック診断フロー
flowchart TD
A[Qiita で記事が出ない？] --> B[記事に iknow タグを付けた？]
B --> C[アカウント設定で Qiita 連携済み？]
D[GitHub / Google でエラー？] --> E[アカウント設定で連携し直す]
E --> F[モーダル下部のログイン導線を使う]
G[ファイルが拒否される？] --> H[対応形式か確認（pdf/docx/pptx は不可）]
I[MCP がつながらない？] --> J[アカウント設定のエージェント連携]
J --> K[Secret は発行直後のみ]