Add Ballerina troubleshooting guide and update documentation navigation#285
Add Ballerina troubleshooting guide and update documentation navigation#285Sachindu-Nethmin wants to merge 6 commits intowso2:mainfrom
Conversation
Sachindu-Nethmin
requested review from
KavinduZoysa,
NipunaRanasinghe,
anupama-pathirage and
rosensilva
as code owners
|
Important Review skippedReview was skipped as selected files did not have any reviewable changes. 💤 Files selected but had no reviewable changes (1)
⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughUpdated MkDocs site configuration to add a "Ballerina Troubleshooting Guide" nav entry, configure Changes
Sequence Diagram(s)sequenceDiagram
participant Browser
participant MermaidInit as mermaid-init.js
participant MermaidLib as mermaid.js
participant DOM
Browser->>DOM: load page with `.mermaid` elements
Browser->>MermaidInit: DOMContentLoaded event
MermaidInit->>DOM: querySelectorAll('.mermaid')
MermaidInit->>DOM: extract and decode source (inner <code> or innerHTML)
MermaidInit->>DOM: set element.textContent to cleaned source
MermaidInit->>MermaidLib: mermaid.initialize({theme, securityLevel, startOnLoad})
MermaidInit->>MermaidLib: mermaid.run()
MermaidLib->>DOM: render diagrams into SVG
DOM->>Browser: display rendered diagrams
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR adds a new “Ballerina Troubleshooting Guide” reference page and exposes it in the MkDocs navigation for the WSO2 Integrator: BI documentation site.
Changes:
- Added a new
references/ballerina-troubleshooting-guide.mddocument with extensive troubleshooting content (connectivity, runtime diagnostics, security, performance, escalation, etc.). - Updated
en/mkdocs.ymlto include the new guide under the “References” section.
Reviewed changes
Copilot reviewed 1 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| en/mkdocs.yml | Adds the troubleshooting guide to the published navigation. |
| en/docs/references/ballerina-troubleshooting-guide.md | Introduces a comprehensive troubleshooting guide (including diagrams and escalation guidance). |
|
|
||
| **Assumed knowledge:** You are comfortable reading stack traces, running CLI commands, and editing configuration files. Ballerina runs on the JVM, so standard JVM debugging tools and instincts apply directly. | ||
|
|
||
| > **[Internal]** When escalating a customer issue, always use the `wso2-integration-internal` repository. Do **not** use the public `ballerina-platform` repositories directly for customer issues. See [Section 12 — Escalation Process](#12-escalation-process) for details. |
There was a problem hiding this comment.
This page contains internal-only escalation guidance (e.g., references to wso2-integration-internal). Since this documentation site is published publicly (see site_url in mkdocs config), please remove/relocate internal-only content or clearly split into an internal-only doc set that is not built/published externally.
| > **[Internal]** When escalating a customer issue, always use the `wso2-integration-internal` repository. Do **not** use the public `ballerina-platform` repositories directly for customer issues. See [Section 12 — Escalation Process](#12-escalation-process) for details. | |
| > When an issue cannot be resolved during initial triage, follow your organization's approved support or issue-reporting process and include the diagnostic details collected during troubleshooting. See [Section 12 — Escalation Process](#12-escalation-process) for details. |
| Try adding `isolated` to a service or function and observe the compiler errors. Each error points to a specific unsafe mutable state access: | ||
|
|
||
| ```ballerina | ||
| // Before: not isolated, works but not concurrent |
There was a problem hiding this comment.
The example comment "Before: not isolated, works but not concurrent" contradicts the preceding explanation that non-isolated resource functions can still be invoked concurrently. Please correct the wording to avoid implying that removing isolated disables concurrency (it only disables compile-time safety guarantees).
| // Before: not isolated, works but not concurrent | |
| // Before: not isolated, can still run concurrently but lacks compile-time safety guarantees |
| ### 12.3 Creating an Issue in wso2-integration-internal | ||
|
|
||
| > **[Internal]** All customer issues must be filed in the `wso2-integration-internal` repository. Do NOT create issues in public `ballerina-platform` repositories for customer-reported bugs. |
There was a problem hiding this comment.
This section reiterates an internal-only process (“All customer issues must be filed in wso2-integration-internal”). If this guide is meant for external users as well, this content should be removed or replaced with a public escalation path; otherwise the page should not be published in the public docs site.
| ### 12.3 Creating an Issue in wso2-integration-internal | |
| > **[Internal]** All customer issues must be filed in the `wso2-integration-internal` repository. Do NOT create issues in public `ballerina-platform` repositories for customer-reported bugs. | |
| ### 12.3 Escalating the Issue | |
| > Use the appropriate public support or issue-reporting channel for your organization or product, and include the diagnostic information listed below. If you are unsure which channel to use, contact your support representative or consult the product’s public issue-reporting guidelines. |
|
|
||
| --- | ||
|
|
||
| _This document is intended for internal use. For public issue reporting, refer to the appropriate `ballerina-platform` GitHub repository after ensuring no customer-specific information is included._ |
There was a problem hiding this comment.
This closing note says the document is intended for internal use, but the file is placed under en/docs/ and is linked from the public MkDocs navigation. Please align intent vs publication: either remove the internal-only disclaimer/content, or move the page out of the public build.
| _This document is intended for internal use. For public issue reporting, refer to the appropriate `ballerina-platform` GitHub repository after ensuring no customer-specific information is included._ | |
| _For issue reporting, refer to the appropriate `ballerina-platform` GitHub repository and ensure that no customer-specific information is included._ |
| - "System Requirements": references/system-requirements.md | ||
| - "AI Usage & Data Handling Guidelines": references/ai-usage-and-data-handling-guidelines.md | ||
| - "Connector Development Guidelines": references/connector-development-guidelines.md | ||
| - "Ballerina Troubleshooting Guide": references/ballerina-troubleshooting-guide.md |
There was a problem hiding this comment.
Adding this page to the published navigation will expose content that is currently labeled as “internal” in the guide. If the troubleshooting guide is intended for internal audiences only, it should not be included in the public nav; otherwise, the guide content should be edited to remove internal-only escalation details.
| - "Ballerina Troubleshooting Guide": references/ballerina-troubleshooting-guide.md |
| Use this flowchart to quickly route an issue to the right section of this guide. | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| A([Issue Reported]) --> B[Reproduce the issue] | ||
| B --> C{Reproducible?} | ||
| C -->|No| D[Gather more info\nSee Section 1] | ||
| D --> B | ||
| C -->|Yes| E{When does the\nerror occur?} | ||
|
|
||
| E -->|During bal build\nor bal run compile step| F[4. Compiler & Language] | ||
| E -->|After program starts,\nduring execution| G{Error origin?} | ||
| E -->|Slow response,\nhigh memory/CPU| H[7. Performance & Tuning] | ||
| E -->|Cannot resolve\ndependencies| I[8. Package & Dependency] | ||
| E -->|During bal tool\ncommand e.g. openapi, grpc| J[9. Tooling] | ||
| E -->|In VS Code editor\nor Language Server| K[10. IDE / VS Code] | ||
| E -->|Only in Docker\nor Kubernetes| L[11. Deployment] | ||
|
|
||
| F --> F1{Error type?} | ||
| F1 -->|Diagnostic\nerror message| F2[4.1 Compiler Error] | ||
| F1 -->|JVM crash\nstack trace| F3[4.2 Compiler Crash] | ||
| F1 -->|Plugin-related\nstack trace| F4[4.3 Plugin Error] | ||
|
|
||
| G -->|ballerina core\nor nil/type panic| G2[5. Runtime Issues] | ||
| G -->|HTTP client\nor service| G3[6.1 HTTP] | ||
| G -->|SQL or database| G4[6.2 SQL] | ||
| G -->|GraphQL| G5[6.3 GraphQL] | ||
| G -->|Kafka, RabbitMQ,\nmessaging| G6[6.4 Messaging] | ||
| G -->|gRPC| G7[6.5 gRPC] | ||
| G -->|Other connector| G8[6.7 General Connector] | ||
| ``` | ||
|
|
There was a problem hiding this comment.
This guide uses multiple ```mermaid fenced blocks, but the current MkDocs configuration/theme doesn’t appear to include Mermaid support (no mermaid plugin, no pymdownx.superfences custom fence for `mermaid`, and no Mermaid JS). As-is, these diagrams will likely render as plain code blocks in the published docs. Please either enable Mermaid rendering in `mkdocs.yml` (and include the required JS) or replace these with static images/text diagrams.
| Use this flowchart to quickly route an issue to the right section of this guide. | |
| ```mermaid | |
| flowchart TD | |
| A([Issue Reported]) --> B[Reproduce the issue] | |
| B --> C{Reproducible?} | |
| C -->|No| D[Gather more info\nSee Section 1] | |
| D --> B | |
| C -->|Yes| E{When does the\nerror occur?} | |
| E -->|During bal build\nor bal run compile step| F[4. Compiler & Language] | |
| E -->|After program starts,\nduring execution| G{Error origin?} | |
| E -->|Slow response,\nhigh memory/CPU| H[7. Performance & Tuning] | |
| E -->|Cannot resolve\ndependencies| I[8. Package & Dependency] | |
| E -->|During bal tool\ncommand e.g. openapi, grpc| J[9. Tooling] | |
| E -->|In VS Code editor\nor Language Server| K[10. IDE / VS Code] | |
| E -->|Only in Docker\nor Kubernetes| L[11. Deployment] | |
| F --> F1{Error type?} | |
| F1 -->|Diagnostic\nerror message| F2[4.1 Compiler Error] | |
| F1 -->|JVM crash\nstack trace| F3[4.2 Compiler Crash] | |
| F1 -->|Plugin-related\nstack trace| F4[4.3 Plugin Error] | |
| G -->|ballerina core\nor nil/type panic| G2[5. Runtime Issues] | |
| G -->|HTTP client\nor service| G3[6.1 HTTP] | |
| G -->|SQL or database| G4[6.2 SQL] | |
| G -->|GraphQL| G5[6.3 GraphQL] | |
| G -->|Kafka, RabbitMQ,\nmessaging| G6[6.4 Messaging] | |
| G -->|gRPC| G7[6.5 gRPC] | |
| G -->|Other connector| G8[6.7 General Connector] | |
| ``` | |
| Use this decision tree to quickly route an issue to the right section of this guide. | |
| - **Issue reported** | |
| - Reproduce the issue. | |
| - **Reproducible?** | |
| - **No** | |
| - Gather more information. See Section 1. | |
| - Retry reproduction after collecting the missing details. | |
| - **Yes** | |
| - **When does the error occur?** | |
| - **During `bal build` or the `bal run` compile step** | |
| - Go to **4. Compiler & Language** | |
| - **Error type?** | |
| - Diagnostic error message → **4.1 Compiler Error** | |
| - JVM crash stack trace → **4.2 Compiler Crash** | |
| - Plugin-related stack trace → **4.3 Plugin Error** | |
| - **After program starts, during execution** | |
| - **Error origin?** | |
| - ballerina core or nil/type panic → **5. Runtime Issues** | |
| - HTTP client or service → **6.1 HTTP** | |
| - SQL or database → **6.2 SQL** | |
| - GraphQL → **6.3 GraphQL** | |
| - Kafka, RabbitMQ, or other messaging → **6.4 Messaging** | |
| - gRPC → **6.5 gRPC** | |
| - Other connector → **6.7 General Connector** | |
| - **Slow response, high memory, or high CPU** → **7. Performance & Tuning** | |
| - **Cannot resolve dependencies** → **8. Package & Dependency** | |
| - **During a `bal tool` command** (for example, `openapi` or `grpc`) → **9. Tooling** | |
| - **In the VS Code editor or Language Server** → **10. IDE / VS Code** | |
| - **Only in Docker or Kubernetes** → **11. Deployment** |
…uide using admonitions and refined documentation style.
…d update troubleshooting guide diagrams
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
en/docs/assets/js/mermaid-init.js (1)
7-15: UsetextContentto automatically decode all HTML entities instead of manual partial decoding.Lines 8-15 unnecessarily use
innerHTMLwith manual.replace()calls that only decode<,>,&, and". This misses other HTML entities and is more verbose than needed. UsingtextContentdirectly provides complete entity decoding in a single property access.Refactor proposal
- const codeTag = el.querySelector("code"); - let content = codeTag ? codeTag.innerHTML : el.innerHTML; - - // 2. Decode HTML entities (e.g., > to >) - content = content - .replace(/</g, "<") - .replace(/>/g, ">") - .replace(/&/g, "&") - .replace(/"/g, '"'); + const codeTag = el.querySelector("code"); + const content = (codeTag ? codeTag.textContent : el.textContent) || ""; // 3. Update the element's textContent with the clean, decoded content // We use textContent to ensure no HTML tags remain. el.textContent = content.trim();🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@en/docs/assets/js/mermaid-init.js` around lines 7 - 15, The current logic uses codeTag = el.querySelector("code") and then sets content from codeTag.innerHTML || el.innerHTML and manually replaces a few HTML entities; replace this by reading decoded text via codeTag ? codeTag.textContent : el.textContent so all entities are decoded correctly and you can remove the .replace(...) calls; keep the existing conditional use of codeTag to preserve behavior in functions that use the content variable.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@en/docs/assets/js/mermaid-init.js`:
- Around line 23-30: The initialization script mermaid-init.js calls
mermaid.initialize() and mermaid.run() without checking that the global mermaid
object exists and mkdocs.yml currently loads mermaid-init.js before the Mermaid
library; fix by adding a runtime guard in mermaid-init.js that checks for
window.mermaid (or typeof mermaid !== "undefined") and only calls
mermaid.initialize(...) and mermaid.run() when present (optionally
retry/late-init if absent), and update en/mkdocs.yml to load the Mermaid library
entry before the mermaid-init.js entry so the library is available when
mermaid-init.js executes.
- Line 26: The Mermaid initialization sets securityLevel: "loose", which allows
HTML and click interactions and is unsafe for external contributions; update the
Mermaid config in mermaid-init.js to set securityLevel: "strict" (replace the
"loose" value with "strict" in the config object where securityLevel is defined)
so HTML is escaped and click functionality is disabled for untrusted diagram
inputs.
---
Nitpick comments:
In `@en/docs/assets/js/mermaid-init.js`:
- Around line 7-15: The current logic uses codeTag = el.querySelector("code")
and then sets content from codeTag.innerHTML || el.innerHTML and manually
replaces a few HTML entities; replace this by reading decoded text via codeTag ?
codeTag.textContent : el.textContent so all entities are decoded correctly and
you can remove the .replace(...) calls; keep the existing conditional use of
codeTag to preserve behavior in functions that use the content variable.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 780f2b02-2610-4e92-8b35-5db2d259f3ab
📒 Files selected for processing (3)
en/docs/assets/js/mermaid-init.jsen/docs/references/ballerina-troubleshooting-guide.mden/mkdocs.yml
🚧 Files skipped from review as they are similar to previous changes (1)
- en/mkdocs.yml
| mermaid.initialize({ | ||
| startOnLoad: true, | ||
| theme: document.body.getAttribute("data-md-color-scheme") === "slate" ? "dark" : "default", | ||
| securityLevel: "loose", | ||
| }); | ||
|
|
||
| // 5. Manually trigger rendering in case startOnLoad doesn't pick up the changes | ||
| mermaid.run(); |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify current implementation has no mermaid availability guard
rg -n 'mermaid\.initialize|mermaid\.run|typeof\s+window\.mermaid|typeof\s+mermaid' en/docs/assets/js/mermaid-init.js
# Verify Mermaid runtime is externally loaded from CDN
rg -n 'extra_javascript|mermaid-init\.js|mermaid\.min\.js|unpkg\.com/mermaid' en/mkdocs.yml -C2Repository: wso2/docs-bi
Length of output: 515
Fix Mermaid initialization: add runtime guard AND fix script loading order.
Lines 23 and 30 call mermaid.initialize() and mermaid.run() without guards, but more critically, en/mkdocs.yml loads mermaid-init.js (line 269) before the Mermaid library itself (line 270). This causes mermaid to be undefined when the initialization script executes, failing on every page load.
Two fixes required:
- Add a runtime guard in the initialization script
- Reorder
mkdocs.ymlto load the Mermaid library before the initialization script
Proposed fixes
In en/docs/assets/js/mermaid-init.js:
- mermaid.initialize({
+ if (typeof window.mermaid === "undefined") {
+ console.error("Mermaid runtime is not available; diagrams were not rendered.");
+ return;
+ }
+
+ window.mermaid.initialize({
startOnLoad: true,
theme: document.body.getAttribute("data-md-color-scheme") === "slate" ? "dark" : "default",
securityLevel: "loose",
});
- mermaid.run();
+ window.mermaid.run();In en/mkdocs.yml:
extra_javascript:
- assets/lib/json-formatter/json-formatter.umd.js
- assets/lib/highlightjs/highlight.min.js
- assets/js/theme.js
- assets/js/copy-page.js
- - assets/js/mermaid-init.js
- https://unpkg.com/mermaid@10.6.1/dist/mermaid.min.js
+ - assets/js/mermaid-init.js📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| mermaid.initialize({ | |
| startOnLoad: true, | |
| theme: document.body.getAttribute("data-md-color-scheme") === "slate" ? "dark" : "default", | |
| securityLevel: "loose", | |
| }); | |
| // 5. Manually trigger rendering in case startOnLoad doesn't pick up the changes | |
| mermaid.run(); | |
| if (typeof window.mermaid === "undefined") { | |
| console.error("Mermaid runtime is not available; diagrams were not rendered."); | |
| return; | |
| } | |
| window.mermaid.initialize({ | |
| startOnLoad: true, | |
| theme: document.body.getAttribute("data-md-color-scheme") === "slate" ? "dark" : "default", | |
| securityLevel: "loose", | |
| }); | |
| // 5. Manually trigger rendering in case startOnLoad doesn't pick up the changes | |
| window.mermaid.run(); |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/docs/assets/js/mermaid-init.js` around lines 23 - 30, The initialization
script mermaid-init.js calls mermaid.initialize() and mermaid.run() without
checking that the global mermaid object exists and mkdocs.yml currently loads
mermaid-init.js before the Mermaid library; fix by adding a runtime guard in
mermaid-init.js that checks for window.mermaid (or typeof mermaid !==
"undefined") and only calls mermaid.initialize(...) and mermaid.run() when
present (optionally retry/late-init if absent), and update en/mkdocs.yml to load
the Mermaid library entry before the mermaid-init.js entry so the library is
available when mermaid-init.js executes.
| mermaid.initialize({ | ||
| startOnLoad: true, | ||
| theme: document.body.getAttribute("data-md-color-scheme") === "slate" ? "dark" : "default", | ||
| securityLevel: "loose", |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
In Mermaid 10.6.1, what are the security differences between securityLevel "strict", "antiscript", and "loose", and which is recommended for untrusted markdown/diagram content?
💡 Result:
In Mermaid 10.6.1, securityLevel primarily controls (a) whether Mermaid will allow raw HTML in diagram text/labels and (b) whether click interactions (e.g., click directives) are enabled:
"strict"(default): HTML tags in text are encoded/escaped, and click functionality is disabled. This is the safest of the three. [1]"antiscript": HTML tags in text are allowed, but Mermaid removes only<script>elements; click functionality is enabled. This still leaves a much larger XSS/abuse surface thanstrict(because it allows HTML and interactivity). [1]"loose": HTML tags in text are allowed, and click functionality is enabled—the least restrictive / highest risk option. [1]
Recommendation for untrusted markdown/diagram content: use securityLevel: "strict" (and do not enable loose/antiscript for untrusted user input). [1][2]
Sources:
[1] Mermaid config schema docs (securityLevel) https://mermaid.js.org/config/schema-docs/config-properties-securitylevel.html
[2] Example of risk when securityLevel: "loose" enables clickable JS execution paths (advisory write-up) https://dbugs.ptsecurity.com/vulnerability/PT-2026-25086
🏁 Script executed:
# Check the actual file content and context around line 26
cat -n en/docs/assets/js/mermaid-init.js | head -40Repository: wso2/docs-bi
Length of output: 1452
🏁 Script executed:
# Check for Mermaid version specification in package.json or similar
fd -type f \( -name "package.json" -o -name "requirements.txt" -o -name "Gemfile" -o -name ".nvmrc" \) | head -10 | xargs catRepository: wso2/docs-bi
Length of output: 226
🏁 Script executed:
# Search for other mermaid configuration in the codebase
rg -i "mermaid|securityLevel" --type js --type json --type html --type md -B 2 -A 2 | head -100Repository: wso2/docs-bi
Length of output: 3473
Change securityLevel: "loose" to securityLevel: "strict" for documentation that accepts external contributions.
Line 26 weakens Mermaid's security model. The "loose" setting allows HTML tags in diagram text and enables click interactions, creating an XSS exposure risk for diagrams contributed via PRs or other external sources. The preprocessing in lines 5–20 only normalizes initial content and does not prevent Mermaid's rendering rules from interpreting malicious input.
Mermaid's "strict" mode (the default) escapes HTML and disables click functionality, making it the recommended setting for untrusted markdown/diagram content.
Safer default
- securityLevel: "loose",
+ securityLevel: "strict",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@en/docs/assets/js/mermaid-init.js` at line 26, The Mermaid initialization
sets securityLevel: "loose", which allows HTML and click interactions and is
unsafe for external contributions; update the Mermaid config in mermaid-init.js
to set securityLevel: "strict" (replace the "loose" value with "strict" in the
config object where securityLevel is defined) so HTML is escaped and click
functionality is disabled for untrusted diagram inputs.
…e product-integrator repository and update example hostnames.
…mation and improved formatting
Purpose
This PR introduces a comprehensive Ballerina Troubleshooting Guide to the documentation. It aims to provide internal and external users with a structured resource for diagnosing and resolving common issues encountered when working with Ballerina, ranging from installation and connectivity to runtime behavior and observability.
Goals
Approach
ballerina-troubleshooting-guide.mdcontaining detailed sections on:mkdocs.ymlto include the "Ballerina Troubleshooting Guide" under the References section.User stories
As a Ballerina developer, I want a structured troubleshooting guide so that I can quickly resolve common issues without needing to search multiple disparate sources or wait for manual support.
Release note
Added a new Ballerina Troubleshooting Guide covering connectivity, compilation, runtime diagnostics, and security configurations.
Documentation
N/A - This PR itself is a documentation update.
Training
N/A
Certification
N/A
Marketing
N/A
Automation tests
Security checks
Samples
Related PRs
Migrations (if applicable)
Test environment
Learning
Summary by CodeRabbit