> ## 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

> Symptom-first fixes for sign-in, workspace access, task imports, integrations, API keys, workers, and docs.

Use this page to choose the next concrete action when Cogno setup, import, integration, worker, or docs behavior does not match what you expected.

## Start here

| Symptom                      | First place to check                             |
| ---------------------------- | ------------------------------------------------ |
| Cannot sign in               | Sign-in method and invite state.                 |
| Cannot see a workspace       | Workspace selector, invite link, and membership. |
| Settings page does not load  | Workspace ID and account membership.             |
| Task CSV cannot import       | CSV structure and column mapping.                |
| Integration does not connect | Integration detail page and account permissions. |
| API key is missing           | **Settings > API Keys**.                         |
| Worker is offline            | **Settings > Workers** and the worker process.   |
| Copy for LLM does not work   | Browser clipboard permission.                    |

## Sign-in and workspace access

### Cannot sign in

Check:

1. You are using the same sign-in method you used to create the account.
2. The browser can complete the auth callback.
3. If you came from an invite link, open the invite link again after signing in.
4. If the auth callback shows an error page, capture the visible error text.

### No workspace appears

Check:

1. Open the workspace selector.
2. Confirm you are signed in with the expected account.
3. Ask a workspace owner to send a new invite link from **Settings > Members**.
4. If you have permission to create one, use **Create workspace**.

### Invite link does not add you

Check:

1. Sign in first.
2. Open the invite link in the same browser.
3. Ask for a fresh invite link from **Settings > Members**.
4. Confirm the workspace owner can still see you in the member list after accepting.

## Workspace settings

### Settings shows invalid workspace

The URL may contain a workspace ID that is not available to your account.

Next actions:

1. Go back to the Cogno app root.
2. Select a workspace from the workspace selector.
3. Ask the workspace owner to confirm membership.

### General settings fails to load

Next actions:

1. Refresh the page.
2. Confirm you can open the same workspace from the main Tasks page.
3. Confirm your account still appears in **Settings > Members**.
4. Capture the visible error text.

### Workspace delete is disabled

Check:

1. The workspace has a non-empty title.
2. You typed the exact workspace title in the confirmation dialog.
3. You understand deletion removes tasks, chat history, members, and workspace data.

## Task CSV import

### CSV file is rejected

Cogno requires a header row and at least one task row.

Next actions:

1. Open the CSV in a spreadsheet or text editor.
2. Confirm row 1 contains headers.
3. Confirm at least one later row contains task data.
4. Export again as CSV.

### Mapping complete is disabled

Every CSV column must be mapped or explicitly ignored.

Check:

| Requirement                | Fix                                                                                              |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| Task title exists          | Map a title, name, or summary column to **Task title**.                                          |
| All columns decided        | Map unused columns to **Do not import**.                                                         |
| Status values decided      | Map every source status to a Cogno status.                                                       |
| Assignees decided          | Map every source assignee or choose **Do not assign**.                                           |
| Single-value fields unique | Map only one column to status, assignee, due date, start date, project, parent task, and source. |

### Imported rows are skipped

Rows can be skipped when validation fails.

Common causes:

| Error                                      | Meaning                                                                        |
| ------------------------------------------ | ------------------------------------------------------------------------------ |
| `Task title is required`                   | The mapped title cell is empty.                                                |
| `Invalid due date` or `Invalid start date` | The date cannot be parsed as an absolute date.                                 |
| `Assignee not found`                       | Source assignee was not mapped to a workspace member.                          |
| `Assignee is ambiguous`                    | The source value matches more than one member.                                 |
| `Parent Task not found`                    | Parent reference does not match a task in the same import or previous imports. |
| `Parent Task is ambiguous`                 | Parent reference matches more than one possible task.                          |
| `Parent Task chain contains a cycle`       | Parent references loop back to each other.                                     |

### Parent tasks do not link

Next actions:

1. Map a stable parent ID, title, source URL, or external key to **Parent Task**.
2. Keep each parent row in the same import when possible.
3. Keep source IDs or URLs as **Source** or **Metadata**.
4. Re-import children after parents exist when migrating in separate files.

### Imported tasks miss context

Next actions:

1. Preserve source URL as **Source**.
2. Map labels, priorities, milestones, numbers, issue keys, and custom fields to **Metadata**.
3. Use multiple **Description** columns when long context is split across columns.
4. Keep comments or detailed text in metadata when no direct Cogno field exists.

See [Import task CSVs into Cogno](/docs/task-import).

## Integrations

### Integration card is not clickable

The integration may be marked **Soon**. Available integrations open a detail page and show a chevron.

### Google Calendar does not connect

Next actions:

1. Open **Integrations > Google Calendar**.
2. Select **Connect my Google Calendar**.
3. Complete the Google account flow.
4. Return to the integration page and confirm your member row shows connected.

Each member connects their own Google Calendar.

### Calendar meetings do not get a notetaker

Check:

1. The member invited to the meeting connected their own Google Calendar.
2. The event has a meeting link (Google Meet, Zoom, Microsoft Teams, or Webex).
3. The event starts at least 10 minutes ahead, and **Have Cogno join** is on in its **Upcoming meetings** settings.
4. The event is present on the connected calendar. Shared and delegated calendar events are also eligible.
5. The integration page shows the account as connected.

If a connected teammate is invited to the same meeting, one notetaker covers it for the workspace.

## API keys and workers

### Raw API key is no longer visible

Create a new key. Cogno shows the raw key once after creation and never shows it again.

### API key creation fails

Check:

1. You are a member of the workspace.
2. You have fewer than 25 active keys for this user and workspace.
3. The key name is 255 characters or less.

### Worker does not appear

Next actions:

1. Create or reuse a valid API key.
2. Run:

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

3. Open **Settings > Workers**.
4. Select **Refresh**.

### Worker shows stale or offline

Check:

1. The worker process is still running.
2. The machine has network access.
3. The API key was not revoked.
4. Restart the root `cogno` worker daemon and watch the worker list again.

### Revoke disconnected a worker

Create a replacement key, run `cogno login --token <key>` on the worker machine, then restart the root `cogno` worker daemon.

## Memory

### Memory fails to save

Next actions:

1. Refresh **Settings > Memory**.
2. Confirm you are still signed in.
3. Make a small edit and save again.
4. Copy the visible error text if saving still fails.

### Memory content renders incorrectly

Memory is Markdown. Check headings, bullet indentation, fenced code blocks, and unclosed links.

## Docs and Copy for LLM

### Copy for LLM does not copy

Check:

1. Browser clipboard permission.
2. Whether the page is focused.
3. Whether browser privacy settings block clipboard writes.

### Wrong language appears

Use the language switcher in the top navigation, or open the page directly for the language you want:

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

## Escalation package

When you need help from a teammate or assistant, collect:

1. Workspace name or ID.
2. Page URL.
3. Exact visible error text.
4. Action that produced the problem.
5. Whether the issue reproduces after refresh.
6. Sanitized screenshot or terminal output.
7. Related file header or sample row for CSV import issues.

Remove API keys, private tokens, customer data, and personal contact details before sharing.