Phaeton documentation
Troubleshooting
Common checks for web UI access, setup, activation, charger communication, GX discovery, Auto mode, updates and configuration recovery.
Cannot Reach The Web UI
- Open https://GX-IP:8088/ with the correct device IP address. An additional charger on the same GX uses its own port, such as 8089. A plain http address on that port moves to https by itself.
- On the first visit your browser warns about Phaeton's own certificate. Compare its fingerprint before you continue; see Security.
- Confirm Phaeton is running and that port 8088 is reachable. Check that no firewall on your network or computer blocks it.
- On Venus OS, confirm
/data/rc.localexists and Settings → General → Modification checks → Modifications enabled is on. - For a missing Control Panel in VRM, or one that opens the wrong page, see VRM Control Panel. The checks here are for local access.
If you can sign in to the GX over SSH, check that Phaeton runs and read the newest lines of today's log. The log file name uses the UTC date.
ps | grep phaeton
tail -n 100 /data/phaeton/phaeton.$(date -u +%F).log
The Wizard Appears Again
The setup wizard appears when setup is required. While it is shown, Phaeton does not control charging.
- On a fresh installation, complete the wizard and choose a unique administrator password.
- An older installation that still uses the retired default password also opens the wizard, so you can choose a real password.
- On a device that was set up before and whose administrator account could not be recovered, the wizard first asks for the
allow-setupfile; see Configuration Recovery.
Activation Page Appears
Phaeton is not licensed, or the local license failed validation. While the activation page is shown, Phaeton does not control the charger.
- Use online activation when the device has internet access, and offline activation when it is isolated.
- Open Install details (for support) on the activation page to read the last validation error and the install ID.
- After a reinstall, or to move the license to new hardware, follow Reinstalling or Replacing a Device.
Forgotten Administrator Password
Phaeton keeps its administrator account through restarts, updates and damaged settings, so deleting config.yaml does not reset it. To choose a new password, you need SSH access to the GX.
- Sign in to the GX over SSH.
- Open
/data/phaeton/config.yamlin an editor. In theweb:section, replace the value afterpassword:with your new password, in double quotes. Do not use"or\in it. - Save the file and reboot the GX.
- Sign in with the new password. Phaeton keeps it from then on.
For an additional charger on the same GX, edit the config.yaml in its folder under /data/phaeton-instances/. On another computer, edit the config.yaml in the data directory of your installation. When you can still sign in, change the password under Settings → System → Access instead.
Charger Does Not Connect
- Confirm the local address and port, or the cloud account and charger identification.
- Enable the interface required by your charger: Modbus TCP, local HTTP or approved cloud access.
- Confirm the selected integration matches the exact charger model.
- Check the network route from Phaeton to the charger, and run Test charger connection under Settings → Charger & installation.
- Check the charger's own settings for external control, EMS or load balancing; see the Charger Settings Checklist.
- Review Phaeton logs for connection or decoding errors.
GX Does Not See Phaeton As An EVCS
- Confirm setup and activation are complete. Over Legacy Modbus, Phaeton presents the charger to the GX only while it runs normally; with Phaeton on the GX itself over MQTT and VRM Control Panel on, the GX lists it during setup and activation too, with the warning Initial setup not completed.
- Over MQTT with Phaeton on the GX itself: Charger connection to GX is MQTT discovery and the GX broker address is 127.0.0.1.
- Over MQTT with Phaeton on another computer: Phaeton is paired with the GX. Without pairing, use Legacy Modbus instead.
- Over Legacy Modbus: the GX can reach Phaeton's EVCS Modbus port, 1502 on the GX and 502 on another computer, and no other service uses that port. On another computer, add Phaeton on the GX under Settings → Integrations → Modbus Devices → Saved devices, or switch it on under Discovered devices.
- Give the GX device list a minute to refresh.
- Over Legacy Modbus on a new installation, Phaeton first reads the charger's total energy counter once; until then it answers the GX that it is busy, so the GX never records a zero energy counter. Zaptec, which has no total energy counter, appears at once. The Easee cloud reports the counter about once an hour, so an idle Easee can take up to an hour to appear the first time.
Auto Mode Does Not Start
- Read the charging status on the Charging page first and look it up under Dashboard Status Messages. It names setup, activation, charger, EV, schedule, home battery, grid-threshold, solar-surplus or inverter-overload blocking states. A countdown shows when Auto will start or stop.
- Confirm the charge mode is Auto and that setup and activation are complete.
- Try Manual mode at 6 A. If Manual does not start charging, debug charger-side control before Auto thresholds.
- Confirm the setting Read solar & battery data is on and the dashboard shows plausible solar, grid and battery values.
- Confirm the EV is connected according to charger status.
- Review configured current limits, including a minimum current that is too high, and the home battery rules such as Start at home battery charge (%).
- Check whether the site has enough PV excess for the Auto mode phase.
- Confirm the charger's external control (EMS) settings allow Phaeton to write current setpoints; see the Charger Settings Checklist chapter.
- Run Test charger control and confirm the setpoint is accounted for.
Dashboard status messagesCharging modesCharger Settings Checklist
Dashboard Status Messages
The Charging page shows two kinds of status. Beside the charger name, the operational state says whether Phaeton runs normally; it reads Live when the readings are current. Below the power reading, the charging status says what the charger and Auto are doing, with a detail line below it or under Charging details. The detail gives the values Phaeton compared, such as the solar surplus and the start threshold. The charging status appears only while the operational state reads Live.
Operational State
| Dashboard shows | What it means | What to do |
|---|---|---|
| Live | Phaeton runs normally and the charger readings are current. | Nothing; read the charging status below it. |
| Setup required | First-run setup is not finished, so charging controls stay locked. | Select Open setup and complete the wizard. |
| Activation required | Phaeton needs an activated license before it can control the charger. | Select Open activation; see Activation. |
| Settings recovery | Phaeton could not use its saved settings and started with safe defaults. Charger control is off. | Select Open Settings; see Configuration Recovery. |
| Peblar connection update required | Phaeton connects to Peblar chargers over Modbus TCP and kept your other settings, but still needs the charger's Modbus address. | Enable Modbus access on the charger, enter its address in Settings and save. |
| Charger link disconnected | Phaeton cannot reach the charger. The values shown are the last known readings. | See Charger Does Not Connect. |
| Charger readings out of date or Charger readings unavailable | No new or complete charger reading arrived in time. The values shown are the last known readings. | If it stays, check the charger connection and the logs. |
| Loading charger status, Checking charger link or Phaeton starting | Phaeton is starting, or has not confirmed the charger connection yet. | Wait a moment. |
| Phaeton unavailable or Checking Phaeton status | The browser gets no answer from Phaeton, so charging controls stay locked. | See Cannot Reach The Web UI. |
| Phaeton is not running normally | Phaeton answers but does not run normally. The values shown are the last known readings. | Capture a support bundle and contact support. |
Charger Status
| Dashboard shows | What it means | What to do |
|---|---|---|
| Charger fault: … or Charger error | The charger reports a fault, such as an earth, residual current or temperature fault, and does not charge. | Follow the detail line. The charger's app or display shows more. |
| No EV connected | The charger is reachable but reports no vehicle. | Plug in the car. |
| Waiting for authorization | The car is connected, but the charger waits for an RFID card or app authorization. | Authorize the session at the charger or in its app. |
| Charged | The car is connected but does not take the power offered, usually because it is full or its own charge limit or timer holds it. | Check the charge limit and timer in the car or its app. |
Auto Mode
These titles appear while Phaeton decides in Auto: with the Auto mode Battery-powered or Feed-in, and with Controlled by the Victron GX until the GX takes control.
| Dashboard shows | What it means | What to do |
|---|---|---|
| Starting in … | The start conditions hold. Auto waits out its start delay, which grows after short sessions, up to 4 minutes. | Nothing; charging starts when the countdown ends. |
| Starting to charge | Auto started at the minimum current and waits for the car to draw power. | If it stays, check the charge limit and timer in the car. |
| Stopping in … | Auto charges at the minimum current, but the solar surplus is too small. Charging stops when the countdown ends, unless the surplus returns. | Nothing. With Use battery or grid power on (Settings → Charging), Auto keeps charging for Battery or grid power time (min), 30 minutes by default; Manual keeps charging. |
| Waiting for solar surplus | The solar surplus after the house loads, or the battery charging plus export, is too small to start. | Wait for more sun. Solar surplus to start (W) sets the start level for Battery-powered. |
| Waiting for solar export | Feed-in: the system does not yet export enough to the grid, by default 500 W for a single-phase car and 1,400 W once the car has charged on more than one phase. | Wait for more export, or change the start thresholds under Settings → Charging → Feed-in. |
| Waiting for less grid import | Battery-powered: the grid supplies more than Grid import that blocks a start (W). | Wait until the house loads drop. |
| Waiting for the home battery | Battery-powered leaves the first part of the solar power to the home battery (Home battery share (W)); Feed-in waits while the home battery discharges. | Wait until the home battery charges with its share, or stops discharging. |
| No solar power seen yet | Battery-powered starts only after the GX has reported solar power since its data appeared. | Wait for daylight and check that the GX shows solar power. |
| Waiting for home battery | The home battery is below Start at home battery charge (%). In Scheduled, it is below the minimum of the active price window, or the GX reports no battery charge. | Wait until the home battery has charged, or lower the setting. |
| Home battery low (off-grid) | Off-grid, the home battery is at or below Off-grid stop at battery charge (%). Charging restarts once the battery is 2% above that level and has reached Start at home battery charge (%). | Wait for the home battery to recharge. |
| Waiting for GX data | No solar, grid and battery data from the GX yet, or none for more than two minutes. Charging is stopped. | Check the MQTT connection to the GX or, over Modbus TCP, the GX address and that Modbus TCP is on in the GX. Charging resumes when the data returns. |
| Turn on GX readings for Auto | Read solar & battery data is off, so Auto cannot run. | Turn on Read solar & battery data under Settings → Victron GX → Solar & battery readings. |
| Waiting for inverter capacity | Charging now would overload the inverter. | Wait until other loads drop. |
Controlled By The GX
With the Auto mode Controlled by the Victron GX, the Auto button shows Controlled by Dynamic ESS or Controlled by Opportunity Loads once that GX feature has taken control (Controlled by GX until the GX names it), and GX not connected when the connection to the GX is lost. The GX then decides when and how fast to charge, and the dashboard shows the titles below; once the GX names the feature, they name it instead of GX, such as Paused by Dynamic ESS:
| Dashboard shows | What it means | What to do |
|---|---|---|
| Paused by GX | The GX has control and requests no charging power, or stopped charging because the home battery is low. | Check on the GX or in VRM which feature controls the charger. |
| Waiting for vehicle | The GX requests charging power; Phaeton waits for the car to draw it. | If it stays, check the charge limit and timer in the car. |
| Waiting for GX commands | The GX has sent no charging command for 15 seconds. As on a Victron charging station, the charger holds the minimum current for up to 2 minutes, then stops until the GX sends a command again. | Check the connection to the GX. |
| Preparing phase change | The GX asked for a phase change. Phaeton waits for a safe stop and for the charger to confirm the phases. | Nothing; charging resumes on the new phases. |
Protection, Phases And Schedule
| Dashboard shows | What it means | What to do |
|---|---|---|
| Paused by overload protection, Paused: inverter overload or Paused: inverter input limit | Overload protection paused charging. The detail says when charging starts again by itself or, after a Stop, when you can start it again. | Reduce other loads. The protection settings are under Settings → Charger & installation → Inverter protection. |
| Charging at the minimum: overload | Overload protection holds the minimum current during an overload and for a while after it. | Reduce other loads. |
| Charging at the minimum: inverter hot | The inverter reports a high temperature, so charging stays at the minimum current. | Nothing; it ends a while after the last temperature warning. |
| Current reduced after an overload | After an overload, the current stays lower for a while. | Nothing. |
| Switching to 1 phase or Switching to 3 phases | Charging stops while the charger changes phases and resumes once the charger confirms them. | Nothing. If it stays, see the Charger Settings Checklist. |
| Waiting for verified single-phase charging, Single-phase verification failed or Phase switching disabled | Single-phase only waits for the charger to confirm one phase, or the charger cannot switch phases. | Follow the detail line; after a failed verification, choose Retry single-phase verification on the Charging page. See Phases and inverter protection. |
| Outside scheduled window | Scheduled mode has no active window now. | Check the windows on the Schedule page. |
| Waiting for lower price | The current VRM import price is above the active window's limit. | Wait, or raise the window's price limit. |
| Prices unavailable | The current interval has no usable VRM price, so charging pauses. The fallback rate in Session pricing does not allow charging. | Check the VRM price connection. |
| Price allows charging | The current price is within the active window's limit. | Nothing. |
| Charging stopped | A price-controlled window is held by a Stop. | Start charging to let the schedule and price rules run. |
Codes On The GX
When the GX connects over MQTT, Phaeton reports errors, warnings and refused commands to it as a Victron charging station does. Victron's manual lists them by code, such as E-01 or W-104, with the charging station's meaning. The GX shows an error with its GX code, such as "#01 GND not present", and a warning by its message alone. It records a refused command but, up to Venus OS 3.85, does not show it. With Phaeton the codes mean:
| Code | Shown on the GX | With Phaeton |
|---|---|---|
| E-01 | #01 GND not present | The charger reports a protective earth fault. |
| E-02 | #02 Welded contacts | The charger reports a welded relay or contactor. |
| E-03 | #03 CP input short-circuit | The charger reports a control pilot fault. |
| E-04 | #04 Residual current | The charger's residual current protection tripped. |
| E-05 | #05 Over temperature | The charger reports that it is too hot. |
| W-101 | Initial setup not completed | Phaeton's setup or activation is not finished, or Phaeton is in configuration recovery. Finish setup or activation in Phaeton's web UI, or see Configuration Recovery. |
| W-104 | GX communication warning | No GX data for more than two minutes. In Auto, the Dashboard shows Waiting for GX data and charging stops until the data returns; in other modes it warns No data from the Victron GX. Check the network connection to the GX. |
| W-105 | Overload detected | Overload protection acted; shown until a car is connected again. |
| W-106 | Overload active | Overload protection holds charging. |
| W-109 | The charging current is limited due to inverter overtemperature | Inverter temperature protection holds the minimum current. |
| N-305 | Not shown (Victron's manual: Initial setup not completed) | A start or stop from the GX was refused for the same reasons as W-101. |
| N-307 | Not shown (Victron's manual: Overload active - can't start charging) | A start was refused during an overload hold. |
An error code appears only when the charger integration reports the cause; not every charger does, and other charger faults show only in the status. The other codes in Victron's manual do not occur with Phaeton. Over legacy Modbus TCP the GX reads no codes; faults then show only in the status.
Updates Fail
- For a release repository update, confirm the device has internet access.
- With a private repository, check Repository URL and Access token (for private repos) under Settings → System → Maintenance, in Advanced.
- For an uploaded package, use the official signed
.phaeton-updatepackage for your device platform. - A timeout or a 502 error through VRM Control Panel does not mean the update failed. Reload the page and check the installed version first.
- If Phaeton reports that an earlier update is still being checked, wait a few minutes and try again.
- Review the logs for download, checksum, signature or unpack errors.
Configuration Recovery
If Phaeton cannot use its saved configuration, for example because config.yaml is damaged or missing on a device that was set up before, it starts in configuration recovery instead of stopping. The web UI works with safe defaults, but charger control stays off and Phaeton does not run as a charging station for the GX, so default charger or GX addresses are never used. The dashboard shows Settings recovery; over MQTT the GX shows W-101 or no longer lists the charger.
- Sign in with your existing administrator account. Phaeton keeps it even when
config.yamlcannot be read, because it saves a private copy inconfig-web.jsonwhenever settings are saved. - Open Settings. The status line names the file and the problem, and where Phaeton kept a copy of the original file.
- Settings shows safe defaults, not your saved values, so enter your settings again, at least the charger and the GX connection, using the copy as a reference, and select Apply changes. Or select Reset charger settings, under Settings → System → Maintenance in Advanced, to start from the defaults. A reset keeps your sign-in and saved passwords.
- Confirm the restart. Phaeton restarts by itself and leaves recovery once the settings are valid.
Phaeton keeps the damaged config.yaml until one of these repairs succeeds. Deleting config.yaml does not remove the administrator account either; Phaeton then starts in recovery mode.
If the account itself cannot be recovered, Phaeton shows the setup wizard but finishes it only after local proof that you own the device. Sign in to the GX over SSH, run the command below and submit the wizard again. The wizard names the exact path; on another computer or for an additional charger, it is in that installation's data directory. The file allows one new account and is removed once setup completes.
touch /data/phaeton/allow-setup
Capture Logs For Support
- Open Logs.
- Set Device log level to DEBUG. It applies to the whole device and returns to INFO after 15 minutes.
- Under More, choose Clear displayed logs.
- Reproduce the Manual 6 A test, then the Auto-mode attempt.
- Select Contact support. The portal opens with a support bundle attached automatically. Keep Phaeton open until the attachment appears.
Capture the bundle after you reproduce the problem, before you restart Phaeton or reconnect the charger. To confirm a fix, capture a new bundle while the charger is connected, so it includes the current status.
The bundle holds the Phaeton version, the current status, diagnostics and the log. Folder paths, email addresses, passwords, tokens and full device identifiers are removed: IP addresses keep only their last number, and serial, install and license identifiers keep only their last four characters. More › Download support bundle downloads the same bundle for an offline copy. Use Download full log only when support asks for the original log file.
DEBUG and TRACE are for temporary diagnostics. Phaeton returns the level to INFO after 15 minutes to protect the GX storage. On Venus OS, the log files are /data/phaeton/phaeton.<date>.log, one per day.
Information For Support
- Phaeton version.
- Platform, charger model, and charger firmware.
- Selected charger integration.
- Whether onboarding and activation are complete.
- Whether Test charger connection succeeds, and in the setup wizard Test GX data connection.
- Relevant log excerpt from the Logs page.
- Install ID if the issue is licensing related.
- Describe what happened, when it happened and what you expected on the Support page. Review the attached bundle, then select Send to support. If Phaeton cannot open the portal, choose More, then Download support bundle, and attach it there yourself, or email info@virtunet.nl.
For commercial licensing questions, email info@virtunet.nl as well.