> ## Documentation Index
> Fetch the complete documentation index at: https://cogno.studio/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> sign-in、ワークスペース access、task import、integrations、API keys、マシン、docsの症状別対処です。

このページは、Cognoのsetup、import、integration、マシン、docsが期待通りに動かない時に、次に行う具体的な操作を選ぶためのものです。

## 最初に見る場所

| Symptom | First place to check |
| - | - |
| sign inできない | sign-in methodとinvite state。 |
| ワークスペースが見えない | ワークスペース selector、invite link、membership。 |
| Settings pageが開かない | ワークスペース IDとaccount membership。 |
| task CSVをimportできない | CSV structureとcolumn mapping。 |
| integrationがconnectしない | integration detail pageとaccount permissions。 |
| API keyが見つからない | **設定 → APIキー**。 |
| マシンが仕事を実行できない | Cognoデスクトップアプリの **設定 → コンピューター**。 |
| Desktopのupdateが必要 | **Cognoをアップデート**を選び、画面の進捗を確認する。 |
| Copy for LLMが動かない | browser clipboard permission。 |

### Desktopのupdateが必要

Cognoは、アプリの他の画面を開く前に、現在の署名済みDesktop releaseへのupdateを求める場合があります。この画面は閉じられません。**Cognoをアップデート**を選ぶと開始します。Cognoがreleaseをdownload・installしている間は、progress barと、設定言語に対応した3件のupdate内容が表示されます。横にswipeするか、3つのpage indicatorを使って移動できます。

installが完了するとCognoは自動的に再起動します。更新後のアプリが開いたら、welcome画面で **Cognoをはじめる** を選びます。in-app updateを利用できない場合は、**Cognoをアップデート**を選ぶと署名済みinstallerがdownloadされます。手動でinstallしてCognoをもう一度開いてください。errorが表示された場合は **もう一度試す** または **インストーラーをダウンロード** を選びます。任意のupdateがあるときは、タイトルバーの右端に **再起動して更新** が表示されます。選んでから **今すぐ再起動** を選びます。このupdateが失敗した場合は同じ場所に **更新に失敗しました** が表示されるので、選んでから **もう一度試す** または **ダウンロードページを開く** を選び、最新の署名済みreleaseを手動で入手します。

## Sign-inとワークスペース access

### Sign inできない

確認します。

1. account作成時と同じsign-in methodを使っている。
2. emailで新規登録した場合は、受信した最新の6桁confirmation codeをsignup画面へ入力する。メールは別deviceで読んでもよいが、codeはsignupを開始したbrowserへ入力する。
3. GoogleまたはApple sign-inの場合は、browserがauth callbackを完了できる。
4. invite linkから来た場合は、sign in後にinvite linkをもう一度開く。
5. auth callbackがerror pageを表示する場合は、visible error textを控える。

### ワークスペースが表示されない

確認します。

1. ワークスペース selectorを開く。
2. 期待するaccountでsign inしている。
3. ワークスペース ownerに **設定 → メンバー** から新しいinvite linkを送ってもらう。
4. 自分で作成できる場合は **ワークスペースを作成** を使う。

### Invite linkで追加されない

確認します。

1. 先にsign inする。
2. 同じbrowserでinvite linkを開く。
3. **設定 → メンバー** からfresh invite linkをもらう。
4. accept後、ワークスペース ownerがmember listで自分を確認できる。

## ワークスペース settings

### Settingsがinvalid ワークスペースになる

URLのワークスペース IDがcurrent accountから使えない可能性があります。

次の操作を行います。

1. Cogno app rootに戻る。
2. ワークスペース selectorからワークスペースを選ぶ。
3. ワークスペース ownerにmembershipを確認してもらう。

### General settingsが読み込めない

次の操作を行います。

1. pageをrefreshする。
2. main Tasks pageから同じワークスペースを開けるか確認する。
3. 自分のaccountが **設定 → メンバー** に残っているか確認する。
4. visible error textを控える。

### ワークスペース deleteがdisabled

確認します。

1. ワークスペース titleが空ではない。
2. confirmation dialogにexact ワークスペース titleを入力している。
3. deletionによりtasks、chat history、members、ワークスペース dataが消えることを理解している。

## Task CSV import

### CSV fileがrejectedされる

Cognoはheader rowと少なくとも1件のtask rowを必要とします。

次の操作を行います。

1. spreadsheetまたはtext editorでCSVを開く。
2. row 1がheadersになっていることを確認する。
3. 2行目以降にtask dataがあることを確認する。
4. CSVとしてexportし直す。

### Mapping completeがdisabled

すべてのCSV columnはmapするか、明示的にignoreする必要があります。

確認します。

| Requirement | Fix |
| - | - |
| Task title exists | title、name、summary columnを **Task title** にmapする。 |
| All columns decided | 使わないcolumnsを **Do not import** にmapする。 |
| Status values decided | すべてのsource statusをCogno statusにmapする。 |
| Assignees decided | すべてのsource assigneeをmapするか **Do not assign** を選ぶ。 |
| Single-value fields unique | status、assignee、due date、start date、project、parent task、sourceは1 columnだけにmapする。 |

### Imported rowsがskippedされる

validationに失敗したrowsはskippedされます。

よくある原因です。

| Error | Meaning |
| - | - |
| `Task title is required` | mapped title cellが空。 |
| `Invalid due date` または `Invalid start date` | dateがabsolute dateとしてparseできない。 |
| `Assignee not found` | source assigneeがワークスペース memberにmapされていない。 |
| `Assignee is ambiguous` | source valueが複数memberに一致している。 |
| `Parent Task not found` | parent referenceが同じimportまたは過去importのtaskに一致しない。 |
| `Parent Task is ambiguous` | parent referenceが複数候補に一致している。 |
| `Parent Task chain contains a cycle` | parent referencesが循環している。 |

### Parent tasksがlinkされない

次の操作を行います。

1. stable parent ID、title、source URL、external keyを **Parent Task** にmapする。
2. 可能ならparent rowを同じimportに含める。
3. source IDsまたはURLsを **Source** または **Metadata** に残す。
4. fileを分けてmigrationする場合は、parentsを先にimportしてからchildrenを再importする。

### Imported tasksのcontextが足りない

次の操作を行います。

1. source URLを **Source** として残す。
2. labels、priorities、milestones、numbers、issue keys、custom fieldsを **Metadata** にmapする。
3. 長いcontextが複数columnsに分かれている場合は、複数の **Description** columnsを使う。
4. 直接対応するCogno fieldがないcommentsやdetailed textはmetadataに残す。

詳しくは [タスクCSVをCognoにインポートする](/docs/ja/task-import.md) を見てください。

## 連携

### 連携が一覧に無い

連携ページには、いま接続できるintegrationだけが並びます。対応予定のものは表示しません。Vercel と PostHog は、ワークスペースにすでに接続がある場合だけ表示されます。

### Google カレンダーがconnectしない

次の操作を行います。

1. **連携 → Google カレンダー** を開く。
2. **Connect my Google カレンダー** を選択する。
3. Google account flowを完了する。
4. integration pageに戻り、自分のmember rowがconnectedになっていることを確認する。

Google カレンダーは各memberが自分のaccountを接続します。

### カレンダー meetingsにnotetakerが入らない

確認します。

1. meetingに招待されているmember自身がGoogle カレンダーを接続している。
2. eventにmeeting linkがある(Google Meet / Zoom / Microsoft Teams / Webex)。
3. eventの開始が10分以上先で、**今後のミーティング** の設定にある **Cognoを参加させる** がOnになっている。
4. eventが接続済みカレンダー上にある。共有・委任カレンダーのeventも対象です。
5. integration pageでaccountがconnectedになっている。

接続済みのチームメイトが同じmeetingに招待されている場合は、ワークスペースとして1台のnotetakerがそのmeetingをカバーします。

## API keysとマシン

### Raw API keyが見えなくなった

新しいkeyを作成してください。Cognoはraw keyを作成直後に1回だけ表示し、その後は再表示しません。

### API key creationが失敗する

確認します。

1. 自分がワークスペース memberである。
2. current user / ワークスペースのactive keysが25個未満である。
3. key nameが255文字以下である。

### 「コンピューター」の項目がブラウザでは出ない

**設定 → コンピューター** は、いま使っているパソコンを扱う項目を含みます。ブラウザではその項目が出ません。

ブラウザで出るのは **あなたのコンピューター** — アカウントにサインインしているすべてのコンピューターの一覧 — だけです。**このコンピューター**(**Engine** パネル)、**ログイン時に Cogno を開く**、サーバーの追加は、そのパソコンのCognoデスクトップアプリからしか開けません。

セッションの作業フォルダーは自動でクリーンアップされ、この画面には表示されません。

デスクトップアプリは、ブラウザ右上のアバターメニューの **デスクトップアプリを入手** から取得します。

### プロジェクトを動かす場所がない

environmentとは、マシン上のフォルダーと、そこで作業を動かす設定(AIツール、モデル)のことです。自分のフォルダーはProjectの設定から紐づけます。

次の操作を行います。

1. サイドバーからプロジェクトを開き、名前の横の **⚙** を選ぶ。
2. **Source Folders** の **Add Folder** を選ぶ。CognoデスクトップアプリがOS標準のフォルダー選択画面を開き、選んだフォルダーを紐づけます。
3. そのフォルダーを持つパソコンで操作する。ブラウザでは **Cogno アプリで開く** を選びます。

GitHubで接続されていても、このコンピューターに無いrepositoryは新規Projectメニューで選択できません。このメニューからフォルダーの無いProjectを作ったり、repositoryをcloneしたりすることはありません。

ページ全体は [Projectを設定する](/docs/ja/projects.md) を参照してください。

### マシンが仕事を受け取らない

確認します。

1. そのパソコンでCognoが動いている。デスクトップアプリの **設定 → コンピューター → このコンピューター** の **Engine** パネルが **登録済み** かつ **接続中** であることを確認します。停止していれば **開始** / **再起動** を選びます。macOSでは閉じるボタンでウィンドウがしまわれるだけで、Cognoはメニューバーに残ります。終了はそこの **Quit Cogno** です。
2. machineにnetwork accessがある。
3. 作業に必要なツールが揃っている。**あなたのコンピューター** の各行に **準備完了** / **注意** / **実行不可** / **未報告** が付き、足りないものはそのまま文になって出ます — **エージェント CLI が未インストールです**、**git が未インストールです**、**GitHub CLI が未インストールです** など。
4. 登録済みサーバーの場合は、そのサーバーで `cogno doctor` を実行します。各チェックが判定を返し、失敗したチェックには修正コマンドが表示されます。[自社サーバーでCognoを動かす](/docs/ja/remote-servers.md) を参照してください。

### Runが「このマシンの Claude Code が未接続です」で止まった

Cognoの不具合でも、Taskの問題でもありません。そのターンを実行したマシンの Claude Code（または Codex）CLI のサインインが切れた（期限切れ、またはサインアウト）ため、Run は接続待ちで止まっています。

1. そのマシンのCognoデスクトップアプリでTaskのセッションを開きます。スレッド内の通知に **サインイン** が出ており、選ぶと `claude auth login` / `codex login` を実行するターミナルが開きます。
2. そこでサインインを完了します。Cognoはサインインが通るのを見て、Run を自動で再開します。サインインするまで Run は再開できないため、それまで再開の操作は表示されません。
3. Webアプリから見ている場合や、別のマシンの Run の場合は、通知にそのマシンで実行するコマンドが表示されます。そのマシンでサインインすると、Cognoがそれを検知して通知に **Run を再開** を表示します。

### WindowsでClaudeが「The filename or extension is too long」で起動しない

Claudeに渡す起動設定の量がWindowsの上限を超えると、このエラーが出ることがあります。
エラーに表示される実行ファイルのパスだけでは、どの部分が長すぎるかは分かりません。

**1. 失敗したパソコンを更新する**

そのパソコンに利用可能なCognoデスクトップの更新をインストールし、もう一度作業を実行します。
[Desktopのupdateが必要な場合](/docs/ja/troubleshooting.md#desktopのupdateが必要) を参照してください。

**2. エラーが続く場合は報告する**

エラーが続く場合は、エラー文、デスクトップとEngineのバージョン、影響するWorkspaceをサポートに伝えてください。

### Revokeでマシンが切れた

CLIで動かしているマシンなら、replacement keyを作成し、そのマシンで認証し直します。

```bash theme={"system"}
cogno login --token <key>
cogno
```

登録済みサーバーの場合は `cogno server install` を再実行します。revokeは認証情報のすべての世代を一度に無効化するため、サーバーはもう一度承認される必要があります。

## メモリ

### メモリがsaveできない

次の操作を行います。

1. **設定 → メモリ** をrefreshする。
2. sign in状態を確認する。
3. 小さなeditを行い、もう一度saveする。
4. saveが失敗し続ける場合はvisible error textを控える。

### メモリのrenderingがおかしい

メモリはMarkdownです。headings、bullet indentation、fenced code blocks、閉じていないlinksを確認します。

## DocsとCopy for LLM

### Copy for LLMがcopyしない

確認します。

1. browser clipboard permission。
2. pageにfocusがある。
3. browser privacy settingsがclipboard writesをblockしていない。

### 違う言語が表示される

上部ナビゲーションのlanguage switcherを使うか、目的の言語のページを直接開きます。

```text theme={"system"}
English:  https://cogno.studio/docs/task-import
日本語:   https://cogno.studio/docs/ja/task-import
```

## Escalation package

Cognoのチームに連絡するには、アプリ内のフォームを使います。[問題・要望を報告する](/docs/ja/report-a-problem.md)を参照してください。ページ、リリース、ワークスペースは自動で添えられ、返信はメールで届きます。

teammateまたはassistantに相談する時は、次を集めます。

1. ワークスペース nameまたはID
2. page URL
3. exact visible error text
4. problemを起こしたaction
5. refresh後も再現するか
6. sanitized screenshotまたはterminal output
7. CSV import問題の場合はrelated file headerまたはsample row

共有前にAPI keys、private tokens、customer data、personal contact detailsを削除してください。

## 関連docs

* [問題・要望を報告する](/docs/ja/report-a-problem.md)
* [Cognoを使い始める](/docs/ja/getting-started.md)
* [Task CSVをImportする](/docs/ja/task-import.md)
* [連携を接続する](/docs/ja/integrations.md)
* [API keyを管理する](/docs/ja/api-keys.md)
* [自分のserverでCognoを実行する](/docs/ja/remote-servers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.