## TL;DR

The ID is probably real but wrong for this query: it belongs to a different resource type, a different workspace, or a deleted issue. Verify the ID's resource type and workspace, re-fetch a fresh ID from a live list, and the query works. Never trust an ID copied from another workspace.

"Valid-looking" and "valid for this query" are different things.

## Verbatim query

```text
linear API error: Entity not found on issue query with valid id
```

## Steps

1. Check the ID's resource type
   Linear IDs are opaque strings. Confirm the ID you are querying is actually an issue ID, not a project, team, user, or cycle ID that looks similar.
   Expected: You can say what kind of entity the ID refers to.

2. Confirm the workspace
   Make sure the API key belongs to the workspace that owns the issue. Keys are workspace-scoped.
   Expected: The key's workspace matches the issue's workspace.

3. Re-fetch the ID from a live list
   List issues through the API and pick the ID from the live results instead of trusting the stored one.
   Expected: A fresh ID straight from the current workspace.

4. Re-run the query with the live ID
   Send the same query with the re-fetched ID.
   Expected: The issue data returns with no entity-not-found error.

5. Stop caching IDs across workspaces in the generated client
   Scope any stored Linear IDs to the workspace and resource type they came from.
   Expected: Future queries cannot mix IDs across workspaces.

## Use this when

- Linear GraphQL returns entity not found for an issue ID you believe is valid.
- A generated client stores Linear IDs and reuses them later.
- The same ID works in one workspace and fails in another.

## Not for this skill when

- The failure is a Linear authentication or authorization error (different message).
- The problem is a network failure or timeout.
- The query itself is malformed rather than the ID being wrong.

## Variant phrasings

### "Could not find issue with id"

Same error family, same fix: verify resource type and workspace, re-fetch.

### Entity not found on user or team queries

The same ID-mixing problem hits other resource types. Apply the same verification.

## Why it happens

Linear IDs carry no visible type or workspace information, so a generated client cannot tell an issue ID from a project ID by looking at it. Clients hallucinate IDs, copy them from docs examples, or mix IDs across workspaces and environments. The API then correctly reports that no such entity exists in the queried scope.

## Edge cases

- Archived issues may behave differently from deleted ones; re-fetch to see current state.
- Multi-workspace API keys are easy to mix up; label which workspace each key belongs to.
- An ID from a staging or test workspace never resolves in production.
- IDs copied from the Linear web UI are fine, but only for the workspace shown in that UI.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bqOKOS8PfkTQvg1uomwKSg