Skip to content

Parse Error Stack



POST /api/v1/rum_sourcemap/parse_stack

Overview

Use the corresponding SourceMap to restore the RUM error stack.

Before Calling and Usage Steps

The current key requires rum.Query. The management permission rum.rumCfgManage cannot replace this query permission. Only the Workspace to which the current key belongs is supported. Take appId from content[].appId in the RUM Application Summary; it must be consistent with the app_id in the SDK/error record and cannot be replaced by the internal database UUID. SourceMap is precisely located by application, environment env, and version version; case/whitespace are part of the identifier itself and must exactly match the collection record. Omitting env/version or using an empty string indicates an empty environment/version, not a wildcard for all. The current managed lifecycle requires each to be at most 256 characters.

You must POST an application/json request body; query-encoded body parameters are not allowed, and real stack traces must not be placed in the URL. First upload the corresponding build artifact and confirm that the version is readable, then pass the original error_stack, env, version, error_type, and os; this endpoint does not write comments or update Error Tracking status.

Web currently parses the SDK-standardized “at function @ URL:line:column” format. It matches .js.map in the same directory by URL path; for example, it matches static/js/app.js.map. It is recommended that the map contain sourcesContent to return source context; the source JS can assist function name inference. When os is Android/iOS and error_type=reactnative/reactnative_crash, RN uses the js/ subdirectory and supports common Hermes/Metro addresses; RN native ios_crash/anr_error uses ios/, Android java_crash/anr_error uses android/mapping.txt, and native_crash/anr_crash uses the ABI symbol directory under android/.

For native iOS applications, only ios_crash/anr_error are handled and must match the build dSYM; Android java_crash/anr_error/network_error uses mapping.txt, and native_crash/anr_crash matches the symbol directory by ABI/ABI list. Applications with miniapp/custom/harmonyos or unknown error_type/os currently have no equivalent branch; the response may return js with an empty stacktrace, and this 200 must not be taken as support for that platform.

js is a frame array, and native is text. When a frame does not match a map/source/mapping, the original line and column may be retained without an error; native output may also be partially symbolized or fall back to the original text. Check whether filename/function/context_line match the expected source file; HTTP 200 or a non-empty result does not guarantee that every frame has been restored. The response may contain source code snippets and is intended only for authorized callers. Success responses include Cache-Control:no-store; error responses are not guaranteed to include the same header.

Request Headers

Parameter Name Type Required Description
DF-API-KEY string Y OpenAPI authentication credential for the Workspace.
Example: <DF-API-KEY>
How to obtain or fill in: Obtain an OpenAPI Key with this operation permission from API Key Management in the target Workspace.

Body Request Parameters

Parameter Name Type Required Description
appId string Y Required active application identifier in the current Workspace; it is not the internal RumCfg UUID and cannot be used across Workspaces.
Allow null: False
Example: payment_web
How to obtain or fill in: Obtain from content[].appId in the RUM Application Summary or app_id in the error record.
env string Optional string, defaults to empty environment, maximum 256 characters; it does not represent all environments, and null is not allowed.
Allow empty string: True
Allow null: False
Example: production
How to obtain or fill in: Obtain from the client release environment/error record env, exactly matching the upload.
error_type string Web can usually omit it. iOS supports ios_crash/anr_error; Android supports java_crash/anr_error, native_crash/anr_crash, and network_error; RN uses os in combination to determine the js or native branch. This is currently not a declared enum; unknown values are not guaranteed to be rejected and may also return an empty JS result.
Allow empty string: True
Allow null: False
Example: reactnative
How to obtain or fill in: Obtain from error_type in the error record.
os string Optional string; RN requires Android or iOS, and case is ignored internally. For other types, the platform is usually determined by the application's jsonContent.type; this field does not modify the application platform.
Allow empty string: True
Allow null: False
Example: Android
How to obtain or fill in: Obtain from the operating system field in the error record; this is especially required for RN.
stack string Y Required non-blank string, maximum 131072 characters and 2000 lines; newlines in JSON must be properly escaped. Web currently recognizes the SDK-standardized at function @ URL:line:column format; non-normalized plain V8/Chrome text may return 406, so do not assume any text can be parsed.
Allow null: False
Example: "Error: example\n at say @ https://cdn.example.com/static/js/app.js:1:1"
How to obtain or fill in: Prefer to obtain it verbatim from error_stack in the actual RUM error record, without rewriting line or column numbers yourself.
version string Optional string, defaults to empty version, maximum 256 characters; it does not represent the latest/all versions, and null is not allowed.
Allow empty string: True
Allow null: False
Example: 1.2.3
How to obtain or fill in: Obtain from the actual client release version/error record version, corresponding to the build artifact.

Additional Parameter Notes

Use a Workspace API Key with the “RUM Data Query” permission. The target RUM application must belong to that Workspace. Take app_id from the RUM error record as appId, and error_stack as stack, and pass the record's env and version. When the environment or version is omitted, matching uses an unspecified value; the system looks up the mapping according to the environment and version corresponding to the request.

For React Native calls, also pass os and error_type from the record. reactnative and reactnative_crash on Android and iOS use the JavaScript branch; native crashes use the native parsing branch for the corresponding platform. When the corresponding SourceMap is readable, if React Native is missing these two fields or the combination is unsupported, it returns the same empty result as the console: {"stackType":"js","stacktrace":[]}.

  • When content.stackType is js, content.stacktrace is an array of stack frames. A successful response may retain unmapped original frames; source context fields are returned when the corresponding mapping provides source code.
  • When content.stackType is native, content.stacktrace is non-empty native stack trace text and may retain un-restored frames. For example {"stackType":"native","stacktrace":"java.lang.IllegalStateException\n at com.example.Checkout.submit(Checkout.java:42)"}.
  • Parameters are passed in the JSON request body; the URL query parameter body is prohibited. appId and stack must contain non-whitespace content.
  • Submit one original stack trace per request. stack has a maximum of 131072 characters and 2000 lines; exceeding the limit returns HTTP 400 ft.SourceMapStackTooLong. Calls are also subject to Workspace OpenAPI rate limits and existing SourceMap read limits.
  • Common authentication errors include ft.APIAkKeyFailed (missing API Key), ft.InvalidAPIKey (invalid API Key), ft.APIKeyDisabled (API Key disabled), and ft.Forbidden (insufficient permissions).
  • Missing required fields or incorrect parameter types return HTTP 406 ft.ParameterValidationFailed. A required value that is blank returns HTTP 400 ft.SourceMapRequiredFieldBlank. A non-JSON request or passing the URL query parameter body returns HTTP 400 ft.SourceMapJsonBodyRequired. A JSON syntax error returns HTTP 400 ft.RequestJsonFormatError; when the JSON top level is not an object, it returns HTTP 400 ft.JsonFormatError. Use Accept-Language to select the error message language.
  • Parsing errors include ft.NotFoundRumSet (application not found in the Workspace), ft.SourceMapPackageNotFound (corresponding package not found), ft.SourceMapFileInvalid (invalid mapping file), ft.SourceMapStackFormatInvalid (unrecognized stack format), ft.SourceMapNativeSymbolFileNotFound (missing Android Java mapping file), and ft.SourceMapNativeParseFailed (native parsing produced no usable text).

Request Example

curl --request POST 'https://openapi.guance.com/api/v1/rum_sourcemap/parse_stack' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"appId":"payment_web","env":"production","version":"1.2.3","stack":"Error: example\n    at say @ https://cdn.example.com/static/js/app.js:1:1"}'

Response

HTTP 200, application/json. The example below shows the main fields that can be read directly.

Field Type Description
content.stackType string js or native, used to determine the JSON type of stacktrace.
content.stacktrace array<object> or string An array of frame objects when js, or symbolized text when native; JS frames that are not matched may still return original positions, and an empty array does not mean parsing succeeded.
content.stacktrace[] object A single JS frame; fields with no value may be omitted.
content.stacktrace[].name string SourceMap token name; may be omitted and does not necessarily equal the function name.
content.stacktrace[].function string Function name; may be an input or inferred value.
content.stacktrace[].source_url string Relative URL path of the matched map; typically the URL with the leading / removed and .map appended; may be omitted when there is no value.
content.stacktrace[].filename string Restored source file name or the un-restored position, not the server physical path.
content.stacktrace[].path string Original stack path.
content.stacktrace[].platform string Optional platform marker.
content.stacktrace[].stack_line string Original stack line from the input.
content.stacktrace[].lineno integer 1-based source line number when restoration succeeds; the original position may be retained when unmapped.
content.stacktrace[].colno integer 1-based source column number when restoration succeeds.
content.stacktrace[].context_line array Optional two-element array [source line number, line text]; omitted when there is no context.
content.stacktrace[].context_line[0] integer 1-based source line number.
content.stacktrace[].context_line[1] string Source line text.
content.stacktrace[].pre_context array Array of preceding lines, each item [1-based line number, text], up to about 5 lines, may be [].
content.stacktrace[].pre_context[] array Two-element array [source line number, text].
content.stacktrace[].pre_context[][0] integer Source line number.
content.stacktrace[].pre_context[][1] string Source text of that line.
content.stacktrace[].post_context array Array of following lines, each item [1-based line number, text], up to about 5 lines, may be [].
content.stacktrace[].post_context[] array Two-element array [source line number, text].
content.stacktrace[].post_context[][0] integer Source line number.
content.stacktrace[].post_context[][1] string Source text of that line.
content.declaration object Common declaration for the current Workspace; frames are not recursively inserted.
content.reasonCode string Error response only: machine-readable reason, e.g. active_operation/invalid_scope/registry_missing.
content.action string Error response only: suggested action, e.g. retry_after_operation/verify_ownership/check_scope_and_upload.
content.retryable boolean Error response only: server-suggested retryable flag; cannot be used alone to replay an already-published write.
content.uploadCommitted boolean Only for some single-file error diagnostics: true means the write has been confirmed published; omission does not equal false or confirm that the write was not committed.
content.actualBytes integer Only for some capacity errors: number of bytes counted.
content.maxBytes integer Capacity/read limit in bytes.
content.workspaceUUID string Some restricted error diagnostics: current Workspace UUID.
content.appId string Some restricted error diagnostics: public application identifier.
content.rumCfgUUID string Some restricted error diagnostics: internal application identifier, used only for support troubleshooting and does not replace the request appId.
content.env string Some error diagnostics: environment.
content.version string Some error diagnostics: version.
content.bundleUUID string Some error diagnostics: generation record ID for this request, not uploadId.
content.state string Some error diagnostics: generation state.
content.resource string Some occupancy diagnostics: resource type, e.g. application/bundle.
content.shared boolean Some occupancy diagnostics: whether access is shared.
content.waitedSeconds number Some occupancy diagnostics: seconds already waited.
content.waitSeconds number Some occupancy diagnostics: allowed wait in seconds.
content.waitExhausted boolean Some occupancy diagnostics: this wait was exhausted.
content.elapsedSeconds number Some single-file error diagnostics: operation duration in seconds.
content.phase string Some error diagnostics: failure phase.
content.phaseElapsedSeconds number Some error diagnostics: phase duration in seconds.
{
  "code": 200,
  "content": {
    "stackType": "js",
    "stacktrace": [
      {
        "function": "say",
        "source_url": "static/js/app.js.map",
        "filename": "app.ts",
        "path": "/static/js/app.js",
        "stack_line": "    at say @ https://cdn.example.com/static/js/app.js:1:1",
        "lineno": 1,
        "colno": 1,
        "context_line": [
          1,
          "console.log(1);"
        ],
        "pre_context": [],
        "post_context": []
      }
    ],
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}
{
  "code": 200,
  "content": {
    "stackType": "native",
    "stacktrace": "java.lang.RuntimeException: example\n    at com.example.Payment.run(Payment.java:10)",
    "declaration": {}
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

Error Response

For authentication, rate limiting, and common request errors, see Common Error Definitions.

Storage lifecycle retains compatibility error codes: 409 is usually still ft.InvalidAction; the localized message and content.reasonCode further distinguish the cause. Do not treat message names such as SourceMapOperationBusy as the guaranteed errorCode. During reads, missing package/processing/unavailable is usually 404 ft.SourceMapPackageNotFound; see reasonCode for the specific cause. Back off and retry only when retryable=true is explicitly returned and the current state allows it; when uploadCommitted=true, do not replay a write that has been confirmed published. SourceMapNativeParseFailed explicitly passes through 500; other internal parsing exceptions not passed through uniformly return 500 ft.InternalServerError. Not every frame with a missing map triggers 404.

HTTP Status errorCode Trigger Condition Message or Response Description Handling
406 ft.ParameterValidationFailed Request field is missing, or the field value violates declared validation conditions Parameter parsing failed Check the parameter location, field name, type, and value.
400 ft.RequestJsonFormatError Request JSON syntax is invalid Request JSON format error Correct the JSON according to content.reason, line, and column.
400 ft.JsonFormatError JSON top level is not an object Some JSON file format error Submit a JSON object.
400 ft.SourceMapJsonBodyRequired Not an application/json request body, or a body parameter exists in the URL Pass parameters in the JSON request body; do not use the URL query parameter body. Switch to POST JSON and remove the URL body parameter.
400 ft.SourceMapRequiredFieldBlank appId or stack contains only whitespace stack must contain non-whitespace content. Enter non-empty actual values.
400 ft.SourceMapStackTooLong stack exceeds 131072 characters or splitlines exceeds 2000 lines stack can contain at most 131072 characters and 2000 lines. Reduce the stack in this request and keep the portion to be parsed.
404 ft.NotFoundRumSet Application is not in the current Workspace, has been deleted, or does not exist Specified RUM setting not found Refresh the RUM Application Summary and use the real appId in the current Workspace.
404 ft.SourceMapPackageNotFound No record for the selected environment/version, processing, unavailable, or required file missing Return localized prompts such as record not found/still processing/unreadable/source file does not exist according to reasonCode Check appId/env/version and version status; wait for bundle_processing; for source_files_missing, ask the administrator to check the files or upload again.
409 ft.InvalidAction Upload/read/cleanup conflict, legacy directory takeover not completed, ownership/recovery pending verification, or environment/version outside the lifecycle allowed range Return a specific localized prompt according to reasonCode, e.g. the SourceMap is being used by another upload, read, or cleanup operation Read content.reasonCode/action/retryable: for active_operation/active_upload, etc., back off as instructed; for owner_recovery_required/ownership_verification_required/legacy_invalid, ask the administrator to verify first, and do not delete the occupancy record or force overwrite on your own. For invalid_scope, check that env/version are at most 256 characters.
406 ft.InvalidFileName File relative path, symbolic link, or historical release path is unsafe The SourceMap file path does not meet requirements or contains an unsupported link. Check the relative path and directory structure of the uploaded file. Use a valid relative path within the package, without .., backslashes, absolute paths, or symbolic links; check reasonCode=invalid_path.
413 ft.SourceMapSnapshotTooLarge File snapshot required for reading exceeds the site limit, default 2 GiB The total size of files required for this SourceMap read exceeds the limit Reduce the number of version files or ask the administrator to check the limit.
406 ft.SourceMapStackFormatInvalid Web/RN text cannot be recognized as a usable stack frame Unable to recognize the SourceMap stack format Use the RUM-standardized error_stack and check the application platform and language branch.
406 ft.SourceMapFileInvalid The actually matched map or auxiliary source cannot be read/parsed SourceMap file content is invalid or cannot be parsed Check the build version, map format, and encoding; do not upload arbitrary JSON renamed to .map.
404 ft.SourceMapNativeSymbolFileNotFound The strict Android Java branch is missing mapping.txt Symbol file required for native stack parsing was not found Upload the mapping.txt for the corresponding build; for RN, place it under android/.
500 ft.SourceMapNativeParseFailed The strict Android symbol tool failed/has no valid output, or the native branch ultimately has no non-empty text Native stack parsing failed Keep the traceId and ask the administrator to check the symbol tool and build files; this 500 is explicitly passed through.
500 ft.InternalServerError Database, file read/snapshot, historical configuration, or unhandled parsing exception Internal error Keep the traceId and application/env/version, first confirm the version status and files, then handle according to the actual error; reads can be retried with backoff.

Feedback

Is this page helpful?