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".
설치로 이동 Skills Marketplace 커뮤니티가 만든 AI 스킬을 발견하고 탐색하세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/jeremylongshore/claude-code-plugins-plus-skills --skill linear-common-errors명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
Zip 다운로드 다운로드 중... 이 저장소의 다른 Skills Implement user sign-up and sign-in flows with Clerk.
Use when building authentication UI, customizing sign-in experience,
or implementing OAuth social login.
Trigger with phrases like "clerk sign-in", "clerk sign-up",
"clerk login flow", "clerk OAuth", "clerk social login".
Implement session management and middleware with Clerk.
Use when managing user sessions, configuring route protection,
or implementing token refresh and custom JWT templates.
Trigger with phrases like "clerk session", "clerk middleware",
"clerk route protection", "clerk token", "clerk JWT".
Configure enterprise SSO, role-based access control, and organization management.
Use when implementing SSO integration, configuring role-based permissions,
or setting up organization-level controls.
Trigger with phrases like "clerk SSO", "clerk RBAC",
"clerk enterprise", "clerk roles", "clerk permissions", "clerk organizations".
jeremylongshore
jeremylongshore/claude-code-plugins-plus-skills
GitHub 저장소 열기 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 