Skip to main content
linear-common-errors Diagnose and fix common Linear API and SDK errors.
Use when encountering Linear API errors, debugging integration issues,
or troubleshooting authentication, rate limits, or query problems.
Trigger: "linear error", "linear API error", "debug linear",
"linear not working", "linear 429", "linear authentication error".
Ir a la instalación Skills Marketplace Descubre y explora habilidades de IA creadas por la comunidad.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Mostrar detalles del prompt Un comando directo omite el prompt de revisión. Revisa el origen antes de ejecutarlo.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill linear-common-errorsEl comando permanece en una sola línea. Desplázate horizontalmente para revisarlo antes de copiarlo.
¿Prefieres una copia local? Descarga los archivos que SkillsMP tiene disponibles ahora.
Descargar Zip Descargando... Ocupaciones relacionadas SOC
Basado en la clasificación ocupacional SOC
Explorador de archivos
3 archivos name linear-common-errors description Diagnose and fix common Linear API and SDK errors.
Use when encountering Linear API errors, debugging integration issues,
or troubleshooting authentication, rate limits, or query problems.
Trigger: "linear error", "linear API error", "debug linear",
"linear not working", "linear 429", "linear authentication error".
allowed-tools Read, Write, Edit, Grep, Bash(curl:*) version 1.12.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","linear","api","debugging","authentication"] compatibility Designed for Claude Code, also compatible with Codex and OpenClaw
Linear Common Errors
Overview
Quick reference for diagnosing and resolving common Linear API and SDK errors. Linear's GraphQL API returns errors in response.errors[] with extensions.type and extensions.userPresentableMessage fields. HTTP 200 responses can still contain partial errors -- always check the errors array.
Prerequisites
Linear SDK or raw API access configured
Access to application logs
Understanding of GraphQL error response format
Instructions
Error Response Structure
interface LinearGraphQLResponse {
data : Record <string , any > | null ;
errors ?: Array <{
message : string ;
path ?: string [];
extensions : {
type : string ;
userPresentableMessage ?: string ;
};
}>;
}
import { LinearError , InvalidInputLinearError } from "@linear/sdk" ;
Error 1: Authentication Failures
async function
testAuth
Promise
void
try
const
new
LinearClient
apiKey
env
LINEAR_API_KEY
const
await
viewer
console
log
`OK: ${viewer.name} (${viewer.email} )`
catch
error
any
if
message
includes
"Authentication"
console
error
"API key is invalid or expired."
console
error
"Fix: Settings > Account > API > Personal API keys"
throw
curl -s -X POST https://api.linear.app/graphql \
-H "Authorization: $LINEAR_API_KEY " \
-H "Content-Type: application/json" \
-d '{"query": "{ viewer { id name email } }"}' | jq .
Error 2: Rate Limiting (HTTP 429) Linear uses the leaky bucket algorithm with two budgets:
Request limit : 5,000 requests/hour per API keyComplexity limit : 250,000 complexity points/hour per API keyMax single query complexity : 10,000 points
async function withRetry<T>(fn : () => Promise <T>, maxRetries = 5 ): Promise <T> {
for (let attempt = 0 ; attempt < maxRetries; attempt++) {
try {
return await fn ();
} catch (error : any ) {
const isRateLimited = error.status === 429 ||
error.message ?.includes ("rate" ) ||
error.type === "ratelimited" ;
if (!isRateLimited || attempt === maxRetries - 1 ) throw error;
const delay = 1000 * Math .pow (2 , attempt) + Math .random () * 500 ;
console .warn (`Rate limited (attempt ${attempt + 1 } ), waiting ${Math .round(delay)} ms` );
await new Promise (r =>setTimeout (r, delay));
}
}
throw new Error ("Unreachable" );
}
Check rate limit status via headers:
const resp = await fetch ("https://api.linear.app/graphql" , {
method : "POST" ,
headers : {
Authorization : process.env .LINEAR_API_KEY !,
"Content-Type" : "application/json" ,
},
body : JSON .stringify ({ query : "{ viewer { id } }" }),
});
console .log ("Requests remaining:" , resp.headers .get ("x-ratelimit-requests-remaining" ));
console .log ("Requests limit:" , resp.headers .get ("x-ratelimit-requests-limit" ));
console .log ("Requests reset:" , resp.headers .get ("x-ratelimit-requests-reset" ));
console .log ("Complexity:" , resp.headers .get ("x-complexity" ));
Error 3: Query Complexity Too High Each property = 0.1 pt, each object = 1 pt, connections multiply children by the first argument (default 50). Max 10,000 pts per query.
const heavy = await client.issues ({ first : 250 });
const light = await client.issues ({ first : 50 });
Error 4: Entity Not Found
try {
const issue = await client.issue ("nonexistent-uuid" );
} catch (error : any ) {
if (error.message ?.includes ("Entity not found" )) {
console .error ("Issue may be deleted, archived, or in another workspace." );
console .error ("Try: client.issues({ includeArchived: true })" );
}
}
Error 5: Invalid Input on Mutations import { InvalidInputLinearError } from "@linear/sdk" ;
try {
await client.createIssue ({
teamId : "invalid-uuid" ,
title : "" ,
});
} catch (error) {
if (error instanceof InvalidInputLinearError ) {
console .error ("Invalid input:" , error.message );
}
}
Error 6: Null Reference on Relations
const issue = await client.issue ("uuid" );
const name = (await issue.assignee )?.name ?? "Unassigned" ;
const projectName = (await issue.project )?.name ?? "No project" ;
Error 7: Webhook Signature Mismatch
import crypto from "crypto" ;
function verifyWebhook (payload : string , signature : string , secret : string boolean {
const expected = crypto.createHmac ("sha256" , secret).update (payload).digest ("hex" );
try {
return crypto.timingSafeEqual (Buffer .from (signature), Buffer .from (expected));
} catch {
return false ;
}
}
Error Reference Table Error extensions.type HTTP Cause Fix Authentication required authentication_error401 Invalid/expired key Regenerate at Settings > API Forbidden forbidden403 Missing OAuth scope Re-authorize with correct scopes Rate limited ratelimited429 Budget exceeded Exponential backoff, reduce complexity Query complexity too high query_error400 Deep nesting or large pages Reduce first, flatten query Entity not found not_found200 Deleted/archived/wrong workspace Verify ID, try includeArchived Validation error invalid_input200 Bad mutation input Check field constraints Webhook sig mismatch N/A (local) N/A Wrong signing secret Match LINEAR_WEBHOOK_SECRET
Examples
Catch-All Error Handler import { LinearError , InvalidInputLinearError } from "@linear/sdk" ;
async function handleLinearOp<T>(fn : () => Promise <T>): Promise <T> {
try {
return await fn ();
} catch (error) {
if (error instanceof InvalidInputLinearError ) {
console .error (`Input error: ${error.message} ` );
} else if (error instanceof LinearError ) {
console .error (`Linear error [${error.status} ]: ${error.message} ` );
if (error.status === 429 ) {
console .error ("Rate limited — implement backoff" );
}
} else {
console .error ("Unexpected error:" , error);
}
throw error;
}
}
Resources 