8000 Add a troubleshooting page for the frequently asked errors (#341) · microsoft/vscode-java-debug@0e86ed2 · GitHub
[go: up one dir, main page]
Skip to content

Commit 0e86ed2

Browse files
testforstephentestforstephen
authored
Add a troubleshooting page for the frequently asked errors (#341)
* Add a troubleshooting page for the frequently asked errors * Update the wrong link and remove the unnecessary separator * Update Troubleshooting.md * Make tslint happy * Refine the words per review * Add the missing items parameter for showErrorMessage function * Log the troubleshooting usage * Add a reference in README to link to troubleshooting page * Update the fix steps for illegal request type error * Refine the description words for differnt errors * Add jdk troubleshooting item * Add a link to submit an issue * Add compilation as a try step for ClassNotFoundException * Add the missing license header * Resolve the review comments for troubleshooting doc * Extract dup code to a helper function * Merge activation event to usage data * Refactor showMessage utility method * Add opn to dependency list * update package-lock.json
1 parent 205e387 commit 0e86ed2

File tree

10 files changed

+300
-75
lines changed

10 files changed

+300
-75
lines changed

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,9 @@ Please also check the documentation of [Language Support for Java by Red Hat](ht
9191
- `java.debug.settings.maxStringLength`: the maximum length of string displayed in "Variables" or "Debug Console" viewlet, the string longer than this length will be trimmed, defaults to `0` which means no trim is performed.
9292
- `java.debug.settings.enableHotCodeReplace`: enable hot code replace for Java code. Make sure the auto build is not disabled for [VSCode Java](https://github.com/redhat-developer/vscode-java). See the [wiki page](https://github.com/Microsoft/vscode-java-debug/wiki/Hot-Code-Replace) for more information about usages and limitations.
9393

94+
## Troubleshooting
95+
Reference the [troubleshooting guide](https://github.com/Microsoft/vscode-java-debug/blob/master/Troubleshooting.md) for common errors.
96+
9497
## Feedback and Questions
9598
You can find the full list of issues at [Issue Tracker](https://github.com/Microsoft/vscode-java-debug/issues). You can submit a [bug or feature suggestion](https://github.com/Microsoft/vscode-java-debug/issues/new), and participate community driven [![Gitter](https://badges.gitter.im/Microsoft/vscode-java-debug.svg)](https://gitter.im/Microsoft/vscode-java-debug)
9699

‎Troubleshooting.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Troubleshooting
2+
3+
This document provides the information needed to troubleshoot common errors of Debugger for Java (the debugger). If it does not cover the problem you are seeing, please [log an issue](https://github.com/Microsoft/vscode-java-debug/issues) instead.
4+
5+
## Java Language Support extension fails to start.
6+
The debugger works with [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) (the language server) for source mapping and project support. If the language server fails to start, the debugger will not work as expected. Here is a simple way to check whether the language server is started. Open a .java or a Java project folder in VS Code, and then check the icon at the right side of the status bar. You should see the 👍 icon if the language server is loaded correctly.
7+
8+
![status indicator](https://raw.githubusercontent.com/redhat-developer/vscode-java/master/images/statusMarker.png).
9+
10+
### Try:
11+
1. If you get the error *"The JAVA_HOME environment variable points to a missing folder"* or *"Java runtime could not be located"*, please make sure that the environment variable JAVA_HOME points to a valid JDK. Otherwise, ignore this step.
12+
2. Run VS Code command *"Java: Update project configuration"* to force the language server to reload the current project.
13+
3. Try cleaning the stale workspace cache. Quit all VS Code processes and clean the following cache directory:
14+
- Windows : %APPDATA%\Code\User\workspaceStorage\
15+
- MacOS : $HOME/Library/Application Support/Code/User/workspaceStorage/
16+
- Linux : $HOME/.config/Code/User/workspaceStorage/
17+
4. Try more [troubleshooting guide](https://github.com/redhat-developer/vscode-java/wiki/Troubleshooting) from the language server product site.
18+
19+
## Failed to resolve classpath:
20+
### Reason:
21+
In launch mode, the debugger resolves the classpaths automatically based on the given `mainClass` and `projectName`. It looks for the class specified by `mainClass` as the entry point for launching an application. If there are multiple classes with the same name in the current workspace, the debugger uses the one inside the project specified by `projectName`.
22+
23+
### Try:
24+
1. Check whether the class name specified in `mainClass` exists and is in the right form. The debugger only works with fully qualified class names, e.g. `org.microsoft.app.Main`.
25+
2. Check whether the `projectName` is correct. The actual project name is not always the same to the folder name you see in the File Explorer. Please check the value specified by `projectDescription/name` in the *.project* file, or the `artificatId` in the *pom.xml* for maven project, or the folder name for gradle project.
26+
3. If the problem persists, please try to use the debugger to regenerate the debug configurations in *launch.json*. Remove the existing *launch.json* file and press F5. The debugger will automatically generate a new *launch.json* with the right debug configurations.
27+
28+
## Request type "xyz" is not supported. Only "launch" and "attach" are supported.
29+
### Reason:
30+
The value specified in `request` option of *launch.json* is incorrect.
31+
32+
### Try:
33+
1. Reference the VS Code official document [launch configurations](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations) about how to configure *launch.json*.
34+
2. Try to use the debugger to regenerate the debug configurations in *launch.json*. Remove the existing *launch.json* file and press F5. The debugger will automatically generate a new *launch.json* with the right debug configurations.
35+
36+
## Failed to complete hot code replace:
37+
### Reason:
38+
This error indicates you are doing `Hot Code Replace`. The `Hot Code Replace` feature depends on the underlying JVM implementation. If you get this error, that indicates the new changes cannot be hot replaced by JVM.
39+
40+
### Try:
41+
1. Restart your application to apply the new changes. Or ignore the message, and continue to debug.
42+
2. You can disable the hot code replace feature by changing the user setting `"java.debug.settings.enableHotCodeReplace": false`.
43+
44+
## Please specify the host name and the port of the remote debuggee in the launch.json.
45+
### Reason:
46+
This error indicates you are debugging a remote Java application. The reason is that you don't configure the remote machine's host name and debug port correctly.
47+
48+
### Try:
49+
1. Check whether the remote Java application is launched in debug mode. The typical command to enable debug mode is like *"java -agentlib:jdwp=transport=dt_socket,address=5005,server=y,suspend=n -classpath \<classpath list\> MyMainClass"*, where the parameter *"address=5005"* represents the target JVM exposes *5005* as the debug port.
50+
2. Check the debug port is not blocked by the remote machine's firewall.
51+
52+
## Failed to evaluate. Reason: Cannot evaluate because the thread is resumed.
53+
### Reason:
54+
There are two possible reasons for this error.
55+
- Reason 1: you try to evaluate an expression when the target thread is running. Evaluation only works when your program is on suspend, for example, stopping at a breakpoint or stepping in/out/over.
56+
- Reason 2: you take the VS Code DEBUG CONSOLE view for program input by mistake. DEBUG CONSOLE only accepts input for evaluation, not for program console input.
57+
58+
### Try:
59+
1. For Reason 1, try to add a breakpoint and stop your program there, then evaluate the expression.
60+
2. For Reason 2, try to change the `console` option in the *launch.json* to `externalTerminal` or `integratedTerminal`. This is the official solution for program console input.
61+
62+
## The DEBUG CONSOLE throws Error: Could not find or load main class xyz
63+
### Reason:
64+
You configure the incorrect main class name in `mainClass` of *launch.json*.
65+
66+
### Try:
67+
1. Check whether the class name specified in `mainClass` exists and is in the right form.
68+
2. If the problem persists, it's probably because the language server doesn't load your project correctly. Please reference *"Java Language Support extension fails to start"* paragraph for more troubleshooting info.
69+
70+
## The DEBUG CONSOLE throws ClassNotFoundException
71+
### Reason:
72+
This error indicates your application attempts to reference some classes which are not found in the entire classpaths.
73+
74+
### Try:
75+
1. Check whether you configure the required libraries in the dependency settings file (e.g. *pom.xml*).
76+
2. Run VS Code command *"Java: Force Java compilation"* to force the language server to rebuild the current project.
77+
3. If the problem persists, it's probably because the language server doesn't load your project correctly. Please reference *"Java Language Support extension fails to start"* paragraph for more troubleshooting info.
78+
79+
## Cannot find a class with the main method
80+
### Reason:
81+
When the `mainClass` is unconfigured in the *launch.json*, the debugger will resolve a class with main method automatically. This error indicates the debugger doesn't find any main class in the whole workspace.
82+
83+
### Try:
84+
1. Check at least one main class exists in your workspace.
85+
2. If no main class exists, please create a main class first. Otherwise, it's probably because the language server fails to start. Please reference *"Java Language Support extension fails to start"* paragraph for more troubleshooting info.

‎package-lock.json‎

Lines changed: 13 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -384,6 +384,7 @@
384384
"vscode": "^1.1.6"
385385
},
386386
"dependencies": {
387+
"opn": "^5.3.0",
387388
"vscode-extension-telemetry": "0.0.18"
388389
}
389390
}

‎src/configurationProvider.ts‎

Lines changed: 37 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,13 @@
22
// Licensed under the MIT license.
33

44
import * as vscode from "vscode";
5-
import TelemetryReporter from "vscode-extension-telemetry";
65
import * as commands from "./commands";
6+
import { logger, Type } from "./logger";
7+
import * as utility from "./utility";
78

89
export class JavaDebugConfigurationProvider implements vscode.DebugConfigurationProvider {
910
private isUserSettingsDirty: boolean = true;
10-
constructor(private _reporter: TelemetryReporter) {
11+
constructor() {
1112
vscode.workspace.onDidChangeConfiguration((event) => {
1213
if (vscode.debug.activeDebugSession) {
1314
this.isUserSettingsDirty = false;
@@ -132,75 +133,75 @@ export class JavaDebugConfigurationProvider implements vscode.DebugConfiguration
132133
config.classPaths = result[1];
133134
}
134135
if (this.isEmptyArray(config.classPaths) && this.isEmptyArray(config.modulePaths)) {
135-
const hintMessage = "Cannot resolve the modulepaths/classpaths automatically, please specify the value in the launch.json.";
136-
vscode.window.showErrorMessage(hintMessage);
137-
this.log("usageError", hintMessage);
136+
utility.showErrorMessageWithTroubleshooting({
137+
message: "Cannot resolve the modulepaths/classpaths automatically, please specify the value in the launch.json.",
138+
type: Type.USAGEERROR,
139+
});
138140
return undefined;
139141
}
140142
} else if (config.request === "attach") {
141143
if (!config.hostName || !config.port) {
142-
vscode.window.showErrorMessage("Please specify the host name and the port of the remote debuggee in the launch.json.");
143-
this.log("usageError", "Please specify the host name and the port of the remote debuggee in the launch.json.");
144+
utility.showErrorMessageWithTroubleshooting({
145+
message: "Please specify the host name and the port of the remote debuggee in the launch.json.",
146+
type: Type.USAGEERROR,
147+
});
144148
return undefined;
145149
}
146150
} else {
147-
const ans = await vscode.window.showErrorMessage(
148-
// tslint:disable-next-line:max-line-length
149-
"Request type \"" + config.request + "\" is not supported. Only \"launch\" and \"attach\" are supported.", "Open launch.json");
151+
const ans = await utility.showErrorMessageWithTroubleshooting({
152+
message: `Request type "${config.request}" is not supported. Only "launch" and "attach" are supported.`,
153+
type: Type.USAGEERROR,
154+
}, "Open launch.json");
150155
if (ans === "Open launch.json") {
151156
await vscode.commands.executeCommand(commands.VSCODE_ADD_DEBUGCONFIGURATION);
152157
}
153-
this.log("usageError", "Illegal request type in launch.json");
154158
return undefined;
155159
}
156160
const debugServerPort = await startDebugSession();
157161
if (debugServerPort) {
158162
config.debugServer = debugServerPort;
159163
return config;
160164
} else {
161-
this.log("exception", "Failed to start debug server.");
165+
logger.logMessage(Type.EXCEPTION, "Failed to start debug server.");
162166
// Information for diagnostic:
163167
console.log("Cannot find a port for debugging session");
164168
return undefined;
165169
}
166170
} catch (ex) {
167171
const errorMessage = (ex && ex.message) || ex;
168-
vscode.window.showErrorMessage(String(errorMessage));
169-
if (this._reporter) {
170-
const exception = (ex && ex.data && ex.data.cause)
171-
|| { stackTrace: [], detailMessage: String((ex && ex.message) || ex || "Unknown exception") };
172-
const properties = {
173-
message: "",
174-
stackTrace: "",
175-
};
176-
if (exception && typeof exception === "object") {
177-
properties.message = exception.detailMessage;
178-
properties.stackTrace = (Array.isArray(exception.stackTrace) && JSON.stringify(exception.stackTrace))
179-
|| String(exception.stackTrace);
180-
} else {
181-
properties.message = String(exception);
182-
}
183-
this._reporter.sendTelemetryEvent("exception", properties);
172+
const exception = (ex && ex.data && ex.data.cause)
173+
|| { stackTrace: [], detailMessage: String((ex && ex.message) || ex || "Unknown exception") };
174+
const properties = {
175+
message: "",
176+
stackTrace: "",
177+
};
178+
if (exception && typeof exception === "object") {
179+
properties.message = exception.detailMessage;
180+
properties.stackTrace = (Array.isArray(exception.stackTrace) && JSON.stringify(exception.stackTrace))
181+
|| String(exception.stackTrace);
182+
} else {
183+
properties.message = String(exception);
184184
}
185+
utility.showErrorMessageWithTroubleshooting({
186+
message: String(errorMessage),
187+
type: Type.EXCEPTION,
188+
details: properties,
189+
});
185190
return undefined;
186191
}
187192
}
188193

189-
private log(type: string, message: string) {
190-
if (this._reporter) {
191-
this._reporter.sendTelemetryEvent(type, { message });
192-
}
193-
}
194-
195194
private isEmptyArray(configItems: any): boolean {
196195
return !Array.isArray(configItems) || !configItems.length;
197196
}
198197

199198
private async chooseMainClass(folder: vscode.WorkspaceFolder | undefined): Promise<IMainClassOption | undefined> {
200199
const res = await resolveMainClass(folder ? folder.uri : undefined);
201200
if (res.length === 0) {
202-
vscode.window.showErrorMessage(
203-
"Cannot find a class with the main method.");
201+
utility.showErrorMessageWithTroubleshooting({
202+
message: "Cannot find a class with the main method.",
203+
type: Type.USAGEERROR,
204+
});
204205
return undefined;
205206
}
206207
const pickItems = res.map((item) => {

‎src/constants.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT license.
3+
14
export const JAVA_LANGID: string = "java";
25
export const HCR_EVENT = "hotcodereplace";
36
export const USER_NOTIFICATION_EVENT = "usernotification";

0 commit comments

Comments
 (0)
0