# Common HoshinoBot Deployment Issues with OneBot and gocqhttp: Complete Troubleshooting Guide

> Troubleshoot HoshinoBot deployment issues with OneBot and gocqhttp. Solve common problems like protocol version mismatches, incorrect URLs, and token errors for a smooth setup.

- Repository: [ice9coffee/hoshinobot](https://github.com/ice9coffee/hoshinobot)
- Tags: troubleshooting-guide
- Published: 2026-03-03

---

**Most HoshinoBot deployment failures stem from mismatched OneBot protocol versions, incorrect reverse WebSocket URLs, or missing authentication tokens between the bot and go-cqhttp client.**

HoshinoBot operates as a reverse WebSocket server that requires a OneBot v11-compatible client like go-cqhttp to handle QQ protocol communication. When configuring `ice9coffee/hoshinobot`, administrators must align network settings, resource paths, and authentication tokens across both the bot configuration and the client [`config.yml`](https://github.com/ice9coffee/hoshinobot/blob/main/config.yml). Below are the critical failure points and their fixes based on the actual source implementation.

## OneBot Protocol Version Compatibility

HoshinoBot strictly implements the **OneBot v11** specification. Using older go-cqhttp releases (< v1.0.0) that implement the legacy OneBot v10 API causes immediate connection failures or silent message drops.

Verify your client supports protocol version 11 by checking the `protocol_version` field in your go-cqhttp configuration. According to the repository README, any standard OneBot v11 client—including go-cqhttp, CQHTTP-Mirai, or similar implementations—can connect to HoshinoBot successfully.

## Reverse WebSocket Configuration Errors

The most frequent deployment blocker involves misaligned WebSocket endpoints. HoshinoBot listens on `HOST` and `PORT` defined in [`hoshino/config_example/__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/config_example/__bot__.py) (defaulting to `127.0.0.1:8080`), while go-cqhttp must connect to this endpoint via the reverse WebSocket universal URL.

In [`hoshino/config_example/__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/config_example/__bot__.py), verify these lines:

```python
PORT = 8080
HOST = '127.0.0.1'

```

Then ensure your go-cqhttp [`config.yml`](https://github.com/ice9coffee/hoshinobot/blob/main/config.yml) contains the matching universal endpoint:

```yaml
servers:
  - ws-reverse:
      universal: ws://127.0.0.1:8080/ws/
      reconnect-interval: 5000

```

Test connectivity using `nc -zv 127.0.0.1 8080` on Linux or `telnet 127.0.0.1 8080` on Windows. If the connection fails, check that the bot process has started successfully via [`run.py`](https://github.com/ice9coffee/hoshinobot/blob/main/run.py) and that no other service occupies port 8080.

## Access Token Authentication Failures

When `access-token` is configured, both sides must share the identical secret. If the bot specifies a token in [`__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/__bot__.py) while go-cqhttp sends a different value (or empty), the handshake fails silently.

Set the token in [`__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/__bot__.py) to match go-cqhttp's `default-middlewares` section:

```python

# In hoshino/config_example/__bot__.py

# TOKEN = 'your-secret-token'  # Or leave empty for no auth

```

```yaml

# In go-cqhttp config.yml

default-middlewares: &default
  access-token: 'your-secret-token'  # Must match exactly or both empty

```

## Resource Path and Image Sending Failures

Modules like `flac` or `setu` fail when `RES_DIR` points to a non-existent directory or when `RES_PROTOCOL` is misconfigured. The bot expects a writable resource directory at the path specified in [`__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/__bot__.py).

Configure resource handling according to your deployment architecture:

```python
RES_PROTOCOL = 'file'  # Use 'file' for same-machine deployment

RES_DIR = r'./res/'    # Absolute path recommended for production

RES_URL = 'http://127.0.0.1:5000/static/'  # Only for HTTP mode

```

When `RES_PROTOCOL` is set to `http`, you must run a static file server (e.g., `python -m http.server 5000 --directory ./res`) and ensure `RES_URL` is reachable from the client machine.

## Missing API Keys for External Services

Services like Princess Connect Re:Dive arena lookup (pcrdfans), Mikan RSS, and Twitter integration require API keys stored in dedicated config modules. The bot reads these from [`hoshino/config/priconne.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/config/priconne.py), [`hoshino/config/mikan.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/config/mikan.py), and [`hoshino/config/twitter.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/config/twitter.py) respectively.

If these modules are enabled but keys are missing, external API calls return authentication errors without crashing the bot. Verify each config file contains valid credentials and restart HoshinoBot after editing any configuration file in the `hoshino/config/` directory.

## Network and Firewall Restrictions

Linux distributions with UFW or SELinux enabled often block the WebSocket port by default. Symptoms include connection timeouts where `nc` commands fail despite the bot process running.

Resolve this by opening the specific port:

```bash
sudo ufw allow 8080/tcp

```

For SELinux enforcing mode, you may need to adjust policies or temporarily set permissive mode to test connectivity.

## Python Environment and Dependency Issues

HoshinoBot requires Python 3.8 or higher. Missing packages such as `nonebot`, `aiohttp`, or `quart` cause import errors during startup.

Reinstall dependencies ensuring correct versions:

```bash
python3 -m pip install -r requirements.txt

```

Check [`requirements.txt`](https://github.com/ice9coffee/hoshinobot/blob/main/requirements.txt) in the repository root for the exact dependency specifications. Version conflicts typically manifest as `ImportError` or `AttributeError` in the console output.

## Debugging Hidden Errors

By default, HoshinoBot writes error tracebacks to `log/error.log` as defined in [`hoshino/log.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/log.py). If the bot appears unresponsive but shows no console errors, examine this file for detailed stack traces.

Enable verbose debugging temporarily by setting `DEBUG = True` in [`__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/__bot__.py):

```python
DEBUG = True  # Increases logging verbosity for troubleshooting

```

## Step-by-Step Troubleshooting Checklist

1. **Confirm OneBot v11 compatibility** – upgrade go-cqhttp to v1.0.0+
2. **Match WebSocket URLs** – verify `HOST:PORT` in [`__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/__bot__.py) matches `ws-reverse.universal` in go-cqhttp
3. **Validate access-token** – ensure identical values or both empty
4. **Check resource directories** – confirm `RES_DIR` exists and permissions allow writing
5. **Supply required API keys** – fill in [`priconne.py`](https://github.com/ice9coffee/hoshinobot/blob/main/priconne.py), [`mikan.py`](https://github.com/ice9coffee/hoshinobot/blob/main/mikan.py), and [`twitter.py`](https://github.com/ice9coffee/hoshinobot/blob/main/twitter.py) configs
6. **Open firewall ports** – allow traffic on port 8080 or your custom port
7. **Review error logs** – check `log/error.log` for suppressed tracebacks
8. **Restart both services** – apply configuration changes by restarting bot and client

## Configuration Reference

Complete working configuration examples for both sides of the connection:

**Bot configuration ([`hoshino/config_example/__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/config_example/__bot__.py)):**

```python
PORT = 8080
HOST = '127.0.0.1'
DEBUG = False

RES_PROTOCOL = 'file'
RES_DIR = r'./res/'
RES_URL = 'http://127.0.0.1:5000/static/'

MODULES_ON = {
    'flac',
    'setu',
    # Add other required modules

}

```

**Client configuration ([`go-cqhttp/config.yml`](https://github.com/ice9coffee/hoshinobot/blob/main/go-cqhttp/config.yml)):**

```yaml
account:
  uin: 123456789
  password: ''
  
default-middlewares: &default
  access-token: ''

servers:
  - ws-reverse:
      universal: ws://127.0.0.1:8080/ws/
      reconnect-interval: 5000
      middlewares:
        <<: *default

```

## Summary

- **Use OneBot v11 exclusively** – older protocol versions cause silent failures
- **Align reverse WebSocket settings** – match `HOST:PORT` in [`__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/__bot__.py) with the client's `ws-reverse.universal` URL
- **Synchronize access tokens** – identical values required on both bot and client
- **Configure resource paths** – ensure `RES_DIR` exists and choose `file` or `http` protocol appropriately
- **Check `log/error.log`** – primary location for debugging information when console output appears normal

## Frequently Asked Questions

### What OneBot version does HoshinoBot require?

HoshinoBot requires **OneBot v11** protocol support. Older versions like OneBot v10, found in go-cqhttp releases prior to v1.0.0, are incompatible and will cause connection failures or message handling errors.

### Why does go-cqhttp fail to connect to HoshinoBot?

The client cannot reach the bot's reverse WebSocket server. Verify that `HOST` and `PORT` in [`hoshino/config_example/__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/config_example/__bot__.py) match the `ws-reverse.universal` URL in go-cqhttp's [`config.yml`](https://github.com/ice9coffee/hoshinobot/blob/main/config.yml). Ensure no firewall blocks the connection and that the bot process is actively listening using `nc` or `telnet` tests.

### How do I fix image sending failures in HoshinoBot?

Check `RES_PROTOCOL` and `RES_DIR` settings in [`__bot__.py`](https://github.com/ice9coffee/hoshinobot/blob/main/__bot__.py). For local deployments, use `RES_PROTOCOL = 'file'` and ensure `RES_DIR` points to an existing, writable directory. For remote clients, use `http` mode and verify the static file server specified in `RES_URL` is accessible.

### Where are HoshinoBot error logs stored?

Error logs are written to `log/error.log` in the project root, as implemented in [`hoshino/log.py`](https://github.com/ice9coffee/hoshinobot/blob/main/hoshino/log.py). If the bot behaves unexpectedly but shows no console errors, examine this file for Python tracebacks and API error responses.