Skip to main content 首页 创作者 jeremylongshore tons-of-skills-marketplace linear-common-errors
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 发现并探索由社区构建的 Agent Skills
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace --skill linear-common-errors命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
下载 Zip 下载中... 同仓库更多 Skills langchain-deploy-integration Deploy a LangChain 1.0 / LangGraph 1.0 app to Cloud Run, Vercel, or LangServe correctly — with timeouts sized for chain length, cold-start mitigation, SSE anti-buffering headers, and Secret Manager over .env. Use when prepping a first production deploy, debugging a stream that hangs behind a proxy, or diagnosing p99 latency spikes. Trigger with "langchain deploy", "langchain cloud run", "langchain vercel python", "langchain langserve", or "langchain docker".
langchain-langgraph-agents Build a correct LangGraph 1.0 ReAct agent with create_react_agent — typed tools, error propagation, recursion caps, and stop conditions that actually stop. Use when writing a first tool-calling agent, migrating from AgentExecutor or initialize_agent, or diagnosing an agent that loops on vague prompts. Trigger with "langgraph agent", "create_react_agent", "langgraph tool calling", "AgentExecutor migration", or "agent loop cost".
langchain-langgraph-human-in-loop Build LangGraph 1.0 human-in-the-loop approval flows with interrupt_before /
interrupt_after and Command(resume=...) — JSON-serializable state, clean
resume semantics, and UI wiring for approval decisions. Use when adding an
approval gate before an expensive tool call, wiring a Slack/web UI for agent
approvals, or debugging a graph that crashes on interrupt.
Trigger with "langgraph human in loop", "langgraph interrupt_before",
"langgraph approval flow", "Command resume", "langgraph HITL".
jeremylongshore
jeremylongshore/tons-of-skills-marketplace
打开 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
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 