---
title: "Debugging CheerpJ"
source: "https://cheerpj.com/docs/guides/cheerpj-debug"
---

# Debugging CheerpJ

How to debug CheerpJ in the browser

This guide helps you troubleshoot an application that does not behave as expected with CheerpJ, and collect the information we need if you ask us for help.

## What to do if my application does not work with CheerpJ?

Start with these checks, which cover the most common integration and deployment problems:

- The page loads CheerpJ with a `<script>` tag like this:

```html
<script src="https://cjrtnc.leaningtech.com/5.0/loader.js"></script>
```

- The path to your JARs is correct, and starts with `/app/` when you pass it to [`cheerpjRunJar`](https://cheerpj.com/docs/reference/cheerpjRunJar.md) or [`cheerpjRunMain`](https://cheerpj.com/docs/reference/cheerpjRunMain.md). See the [virtual filesystem](https://cheerpj.com/docs/guides/filesystem.md) guide.
- The Java version passed to [`cheerpjInit`](https://cheerpj.com/docs/reference/cheerpjInit.md) with `version` matches the one the application needs. Java 8 is the default, and applets run on Java 8 only.
- The application runs normally on a desktop JVM.
- The page is served by an HTTP server, not opened from the local disk (`file://`) by double-clicking it.
- The HTTP server supports [Range requests](https://cheerpj.com/docs/guides/basic-server-setup.md#range-requests), and the application files can be reached from the browser.

If the application passes all these checks and still does not work, ask us for help on our [Discord](https://discord.leaningtech.com/) server.

Include the browser’s console output and a HAR file, so we can see what happened. The sections below explain how to save them.

## HTTP limitations

Some CheerpJ features require a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS). When the application is accessed over HTTP, browsers restrict some of their APIs. For example, the clipboard API used by [`clipboardMode: "permission"`](https://cheerpj.com/docs/reference/cheerpjInit.md#permission-mode) is only available over HTTPS. When accessed over HTTP, users can only copy and paste text to the page itself and will have to double press `Ctrl+C` and `Ctrl+V` (`Cmd+C` and `Cmd+V` on macOS).

To resolve this:

- Serve the application over HTTPS, for example through an **HTTPS proxy**.
- Or, for testing, mark the page as a secure context in the browser settings.

## Enable advanced debug logs in CheerpJ

Before saving the browser console output, it can help to turn on advanced debug logs with the [`enableDebug`](https://cheerpj.com/docs/reference/cheerpjInit.md#enabledebug) option of [`cheerpjInit`](https://cheerpj.com/docs/reference/cheerpjInit.md).

```js
cheerpjInit({ enableDebug: true });
```

This option logs much more information when an error occurs, which makes the problem quicker to find.

It is not always needed. Use it when the normal console output does not show anything useful.

> **Heads up**
>
> Enabling debug mode can significantly affect performance. Disable it when not needed.

## Saving the browser console output

To save the browser console output:

- Open your browser and navigate to the application that you are testing with CheerpJ.
- Open the browser’s developer tools by pressing **F12**. Alternatively, click the three dots in the top right corner of the browser, select **More tools** and then **Developer Tools**. ![Open the developer tools](https://cheerpj.com/docs/cheerpj3/assets/open-dev-tools.png)
- Open the **Console** tab. If it is not visible, click the **+** symbol in Edge, or the **>>** symbol in Chrome, and select **Console**.
- If needed, trigger the error in your application.
- Right-click any message in the **Console** tab and select **Save as…** ![Save the console output](https://cheerpj.com/docs/cheerpj3/assets/save-console.png)
- Save the console log to a file and send it to us.

## Extracting a HAR file

A HAR (HTTP Archive) file is a log of the browser’s network activity on a page. It shows loading times, network errors and incorrect server responses, which helps us diagnose problems.

To save a HAR file:

- Open the browser’s developer tools by pressing **F12**. Alternatively, click the three dots in the top right corner of the browser, select **More tools** and then **Developer Tools**. ![Open the developer tools](https://cheerpj.com/docs/cheerpj3/assets/open-dev-tools.png)
- Open the application you are testing with CheerpJ, or reload the page if it is already open, so that the HAR file is complete.
- Open the **Network** tab. If it is not visible, click the **+** symbol in Edge, or the **>>** symbol in Chrome, and select **Network**.
- If needed, trigger the error in your application.
- Click the download icon **↓** at the top right of the **Network** tab. ![Download the HAR file](https://cheerpj.com/docs/cheerpj3/assets/network-tab.png)
- Save the HAR file and send it to us on Discord or GitHub.
