Skip to content

Commit 5fd8809

Browse files
author
name.ZuLu0890
committed
add stellar error decoder
1 parent 50b694f commit 5fd8809

7 files changed

Lines changed: 759 additions & 0 deletions

File tree

‎app/api/telemetry/stellar-errors/route.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import { NextResponse } from "next/server";
2+
import type { UnknownErrorTelemetryPayload } from "@/src/utils/errorDecoder";
3+
4+
export async function POST(request: Request) {
5+
const payload = (await request.json()) as UnknownErrorTelemetryPayload & {
6+
reportedAt?: string;
7+
};
8+
9+
console.warn("Unknown Stellar error reported", payload);
10+
11+
return NextResponse.json({ ok: true });
12+
}

‎src/components/shared/ErrorToast.tsx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
"use client";
2+
3+
import { useState } from "react";
4+
import type { DecodedError, ErrorSeverity } from "@/src/utils/errorDecoder";
5+
6+
interface ErrorToastProps {
7+
error: DecodedError;
8+
onDismiss?: () => void;
9+
}
10+
11+
const severityStyles: Record<ErrorSeverity, string> = {
12+
info: "border-sky-200 bg-sky-50 text-sky-950",
13+
warning: "border-amber-200 bg-amber-50 text-amber-950",
14+
error: "border-rose-200 bg-rose-50 text-rose-950",
15+
};
16+
17+
export function ErrorToast({ error, onDismiss }: ErrorToastProps) {
18+
const [isExpanded, setIsExpanded] = useState(false);
19+
20+
return (
21+
<aside
22+
aria-live="polite"
23+
className={`w-full max-w-xl rounded-lg border p-4 shadow-sm ${severityStyles[error.severity]}`}
24+
role="status"
25+
>
26+
<div className="flex items-start justify-between gap-4">
27+
<div className="min-w-0">
28+
<p className="text-sm font-semibold uppercase">
29+
{error.errorType.replace("_", " ")}
30+
</p>
31+
<p className="mt-1 text-base font-medium">{error.userMessage}</p>
32+
<p className="mt-1 text-sm opacity-80">Code: {error.errorCode}</p>
33+
</div>
34+
35+
{onDismiss ? (
36+
<button
37+
aria-label="Dismiss error"
38+
className="shrink-0 rounded-md px-2 py-1 text-sm font-semibold hover:bg-black/10"
39+
onClick={onDismiss}
40+
type="button"
41+
>
42+
x
43+
</button>
44+
) : null}
45+
</div>
46+
47+
<button
48+
className="mt-3 text-sm font-semibold underline underline-offset-4"
49+
onClick={() => setIsExpanded((current) => !current)}
50+
type="button"
51+
>
52+
{isExpanded ? "Hide troubleshooting" : "Show troubleshooting"}
53+
</button>
54+
55+
{isExpanded ? (
56+
<div className="mt-3 space-y-3 text-sm">
57+
<ul className="list-disc space-y-2 pl-5">
58+
{error.troubleshootingSteps.map((step) => (
59+
<li key={step}>{step}</li>
60+
))}
61+
</ul>
62+
63+
{error.documentationUrl ? (
64+
<a
65+
className="inline-flex font-semibold underline underline-offset-4"
66+
href={error.documentationUrl}
67+
rel="noreferrer"
68+
target="_blank"
69+
>
70+
Stellar documentation
71+
</a>
72+
) : null}
73+
</div>
74+
) : null}
75+
</aside>
76+
);
77+
}

‎src/data/errorCodes.json‎

Lines changed: 302 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
{
2+
"tx_failed": {
3+
"errorCode": "tx_failed",
4+
"errorType": "transaction",
5+
"severity": "error",
6+
"userMessage": "The Stellar network rejected this transaction because at least one operation failed.",
7+
"troubleshootingSteps": [
8+
"Review the operation-specific error shown with this message.",
9+
"Confirm the source account has enough XLM for fees and reserves.",
10+
"Try again after refreshing the account state from the ledger."
11+
],
12+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
13+
},
14+
"tx_too_early": {
15+
"errorCode": "tx_too_early",
16+
"errorType": "transaction",
17+
"severity": "warning",
18+
"userMessage": "This transaction was submitted before its allowed start time.",
19+
"troubleshootingSteps": [
20+
"Wait until the scheduled start time and retry.",
21+
"Check that your device clock is synced.",
22+
"If this came from an automated flow, regenerate the transaction envelope."
23+
],
24+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
25+
},
26+
"tx_too_late": {
27+
"errorCode": "tx_too_late",
28+
"errorType": "transaction",
29+
"severity": "warning",
30+
"userMessage": "This transaction expired before it reached the Stellar network.",
31+
"troubleshootingSteps": [
32+
"Create a fresh transaction and sign it again.",
33+
"Check your network connection before resubmitting.",
34+
"If the issue repeats, increase the transaction time bounds."
35+
],
36+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
37+
},
38+
"tx_missing_operation": {
39+
"errorCode": "tx_missing_operation",
40+
"errorType": "transaction",
41+
"severity": "error",
42+
"userMessage": "The transaction did not include any operation to execute.",
43+
"troubleshootingSteps": [
44+
"Return to the previous step and build the transaction again.",
45+
"Refresh the page if the action button was clicked before the form finished loading.",
46+
"Contact support if the same action keeps creating an empty transaction."
47+
],
48+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
49+
},
50+
"tx_bad_seq": {
51+
"errorCode": "tx_bad_seq",
52+
"errorType": "transaction",
53+
"severity": "warning",
54+
"userMessage": "The account sequence number is out of date.",
55+
"troubleshootingSteps": [
56+
"Refresh the account balance and latest ledger state.",
57+
"Avoid submitting the same signed transaction more than once.",
58+
"Create and sign a new transaction before retrying."
59+
],
60+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
61+
},
62+
"tx_bad_auth": {
63+
"errorCode": "tx_bad_auth",
64+
"errorType": "authorization",
65+
"severity": "error",
66+
"userMessage": "The transaction is missing a required signature or was signed for the wrong network.",
67+
"troubleshootingSteps": [
68+
"Reconnect the wallet for {network}.",
69+
"Confirm every required signer approved the transaction.",
70+
"Make sure the wallet is not signing for testnet while the app is using mainnet."
71+
],
72+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
73+
},
74+
"tx_insufficient_balance": {
75+
"errorCode": "tx_insufficient_balance",
76+
"errorType": "funding",
77+
"severity": "error",
78+
"userMessage": "The source account does not have enough XLM to pay fees and maintain the required reserve.",
79+
"troubleshootingSteps": [
80+
"Add XLM to {accountId} and wait for the balance to update.",
81+
"Reduce the number of operations in the transaction.",
82+
"Remove unused trustlines or offers if the account is close to its reserve limit."
83+
],
84+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
85+
},
86+
"tx_no_source_account": {
87+
"errorCode": "tx_no_source_account",
88+
"errorType": "account",
89+
"severity": "error",
90+
"userMessage": "The source account could not be found on the selected Stellar network.",
91+
"troubleshootingSteps": [
92+
"Confirm the account exists on {network}.",
93+
"Check that the wallet address was copied correctly.",
94+
"Fund the account before submitting a transaction."
95+
],
96+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
97+
},
98+
"tx_insufficient_fee": {
99+
"errorCode": "tx_insufficient_fee",
100+
"errorType": "funding",
101+
"severity": "warning",
102+
"userMessage": "The fee offered for this transaction is too low for the network.",
103+
"troubleshootingSteps": [
104+
"Refresh the recommended fee and build the transaction again.",
105+
"Try again when network traffic is lower.",
106+
"If submitting many operations, increase the maximum fee."
107+
],
108+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
109+
},
110+
"tx_bad_auth_extra": {
111+
"errorCode": "tx_bad_auth_extra",
112+
"errorType": "authorization",
113+
"severity": "error",
114+
"userMessage": "The transaction includes signatures that are not needed.",
115+
"troubleshootingSteps": [
116+
"Disconnect and reconnect the wallet.",
117+
"Regenerate the transaction instead of reusing a previous signed envelope.",
118+
"Ask only the required signer accounts to approve the transaction."
119+
],
120+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/transactions"
121+
},
122+
"tx_internal_error": {
123+
"errorCode": "tx_internal_error",
124+
"errorType": "network",
125+
"severity": "error",
126+
"userMessage": "The Stellar network returned an internal error while processing this transaction.",
127+
"troubleshootingSteps": [
128+
"Wait a moment and submit a fresh transaction.",
129+
"Check the Stellar network status page.",
130+
"Contact support if the problem persists across multiple ledgers."
131+
],
132+
"documentationUrl": "https://status.stellar.org/"
133+
},
134+
"op_bad_auth": {
135+
"errorCode": "op_bad_auth",
136+
"errorType": "authorization",
137+
"severity": "error",
138+
"userMessage": "The operation was not authorized by the required signer.",
139+
"troubleshootingSteps": [
140+
"Confirm the connected wallet controls the operation source account.",
141+
"Reconnect the wallet and sign again.",
142+
"If this is a multisig account, collect approval from the missing signer."
143+
],
144+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/operations"
145+
},
146+
"op_no_source_account": {
147+
"errorCode": "op_no_source_account",
148+
"errorType": "account",
149+
"severity": "error",
150+
"userMessage": "The operation source account does not exist on this network.",
151+
"troubleshootingSteps": [
152+
"Verify the source account address.",
153+
"Create or fund the account before trying again.",
154+
"Check that the app is connected to the intended network."
155+
],
156+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/operations"
157+
},
158+
"op_not_supported": {
159+
"errorCode": "op_not_supported",
160+
"errorType": "operation",
161+
"severity": "error",
162+
"userMessage": "This operation is not supported by the selected Stellar network.",
163+
"troubleshootingSteps": [
164+
"Confirm the network supports this operation type.",
165+
"Update the app or wallet if it is using an outdated SDK.",
166+
"Contact support with the operation name shown in the activity details."
167+
],
168+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/operations"
169+
},
170+
"op_underfunded": {
171+
"errorCode": "op_underfunded",
172+
"errorType": "funding",
173+
"severity": "error",
174+
"userMessage": "The account does not have enough spendable balance for this operation.",
175+
"troubleshootingSteps": [
176+
"Add enough funds to cover the amount, fees, and minimum reserve.",
177+
"Lower the amount and try again.",
178+
"Check for pending offers, trustlines, or claimable balances that affect the reserve."
179+
],
180+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/operations"
181+
},
182+
"op_too_many_subentries": {
183+
"errorCode": "op_too_many_subentries",
184+
"errorType": "account",
185+
"severity": "error",
186+
"userMessage": "The account has reached the maximum number of ledger entries for this operation.",
187+
"troubleshootingSteps": [
188+
"Remove unused trustlines, offers, or data entries.",
189+
"Use a different source account with available ledger entry capacity.",
190+
"Retry after freeing account reserve capacity."
191+
],
192+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/operations"
193+
},
194+
"op_exceeded_work_limit": {
195+
"errorCode": "op_exceeded_work_limit",
196+
"errorType": "network",
197+
"severity": "warning",
198+
"userMessage": "The operation required more network work than the ledger allows.",
199+
"troubleshootingSteps": [
200+
"Try again with fewer operations in the transaction.",
201+
"Split the action into smaller transactions.",
202+
"Retry when network load is lower."
203+
],
204+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/operations"
205+
},
206+
"op_too_many_sponsoring": {
207+
"errorCode": "op_too_many_sponsoring",
208+
"errorType": "account",
209+
"severity": "error",
210+
"userMessage": "The account is sponsoring too many ledger entries.",
211+
"troubleshootingSteps": [
212+
"Stop sponsoring unused entries before retrying.",
213+
"Use another sponsor account with available capacity.",
214+
"Review active sponsorships in the account details."
215+
],
216+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/operations"
217+
},
218+
"op_sponsorship_not_exist": {
219+
"errorCode": "op_sponsorship_not_exist",
220+
"errorType": "account",
221+
"severity": "error",
222+
"userMessage": "The operation tried to revoke a sponsorship that does not exist.",
223+
"troubleshootingSteps": [
224+
"Refresh the account state and try the action again.",
225+
"Confirm the ledger entry is still sponsored.",
226+
"Avoid reusing an old transaction after sponsorship state changes."
227+
],
228+
"documentationUrl": "https://developers.stellar.org/docs/data/apis/horizon/api-reference/errors/result-codes/operations"
229+
},
230+
"contract_error": {
231+
"errorCode": "contract_error",
232+
"errorType": "contract",
233+
"severity": "error",
234+
"userMessage": "The smart contract rejected this request.",
235+
"troubleshootingSteps": [
236+
"Check that the amount, recipient, and vault settings match the contract rules.",
237+
"Refresh the page to load the latest contract state.",
238+
"Contact support with the contract error code if it is shown."
239+
],
240+
"documentationUrl": "https://developers.stellar.org/docs/build/smart-contracts"
241+
},
242+
"storage_error": {
243+
"errorCode": "storage_error",
244+
"errorType": "storage",
245+
"severity": "error",
246+
"userMessage": "The contract storage entry needed for this request is missing, expired, or unavailable.",
247+
"troubleshootingSteps": [
248+
"Refresh contract data from the ledger.",
249+
"Restore archived contract data if the app offers that action.",
250+
"Try again after the latest ledger has been indexed."
251+
],
252+
"documentationUrl": "https://developers.stellar.org/docs/build/guides/conventions/persisting-data"
253+
},
254+
"access_violation": {
255+
"errorCode": "access_violation",
256+
"errorType": "authorization",
257+
"severity": "error",
258+
"userMessage": "The connected account is not allowed to perform this contract action.",
259+
"troubleshootingSteps": [
260+
"Switch to an account with the required role.",
261+
"Confirm the wallet address is the expected beneficiary, admin, or signer.",
262+
"Ask an administrator to update permissions if access should be granted."
263+
],
264+
"documentationUrl": "https://developers.stellar.org/docs/build/guides/conventions/authorization"
265+
},
266+
"auth_error": {
267+
"errorCode": "auth_error",
268+
"errorType": "authorization",
269+
"severity": "error",
270+
"userMessage": "The contract authorization check failed.",
271+
"troubleshootingSteps": [
272+
"Reconnect the wallet and approve the latest authorization request.",
273+
"Confirm the transaction has not expired.",
274+
"Make sure the wallet supports Soroban authorization entries."
275+
],
276+
"documentationUrl": "https://developers.stellar.org/docs/build/guides/conventions/authorization"
277+
},
278+
"budget_exceeded": {
279+
"errorCode": "budget_exceeded",
280+
"errorType": "contract",
281+
"severity": "warning",
282+
"userMessage": "The contract call used more CPU or memory than the network budget allows.",
283+
"troubleshootingSteps": [
284+
"Retry the action with a smaller batch or amount.",
285+
"Wait and try again when network load is lower.",
286+
"Contact support if this is a normal action that should fit within budget."
287+
],
288+
"documentationUrl": "https://developers.stellar.org/docs/build/guides/transactions/fees"
289+
},
290+
"wasm_vm_error": {
291+
"errorCode": "wasm_vm_error",
292+
"errorType": "contract",
293+
"severity": "error",
294+
"userMessage": "The contract runtime failed while executing this request.",
295+
"troubleshootingSteps": [
296+
"Refresh the contract state and retry.",
297+
"Confirm you are using the latest version of the app.",
298+
"Contact support with the transaction hash and contract ID."
299+
],
300+
"documentationUrl": "https://developers.stellar.org/docs/build/smart-contracts"
301+
}
302+
}

0 commit comments

Comments
 (0)