nodejs/hookshot
nodejs/hookshot
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-hookshot.git synced 2025-03-10 13:17:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add troubleshooting doc. (#882)

Browse Source 
* Add troubleshooting doc.

* Create 882.doc

Signed-off-by: Will Hunt <will@half-shot.uk>

* Rename 882.doc to 882.doc

Signed-off-by: Will Hunt <will@half-shot.uk>

---------

Signed-off-by: Will Hunt <will@half-shot.uk>
This commit is contained in:
Will Hunt 2024-01-16 09:43:56 +00:00 committed by GitHub
parent 6d3800a018
commit 1cbd73bb46
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 49 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
changelog.d/882.doc Normal file
View File

@ -0,0 +1 @@
Add troubleshooting page to documentation, to cover common issues.

1
docs/SUMMARY.md
View File

@ -18,6 +18,7 @@
- [JIRA Project](./usage/room_configuration/jira_project.md)
- [📊 Metrics](./metrics.md)
- [Sentry](./sentry.md)
- [🆘 Troubleshooting](./troubleshooting.md)
# 🧑‍💻 Development
- [Contributing](./contributing.md)

47
docs/troubleshooting.md Normal file
View File

@ -0,0 +1,47 @@
Troubleshooting
===============
If you are having difficulties getting set up with hookshot, the advice below might be able to resolve common issues.
If none of these help, please come chat to us in ([#hookshot:half-shot.uk](https://matrix.to/#/#hookshot:half-shot.uk)). Please
try to follow these steps first, as live support is best effort.
## 1. The hookshot bot doesn't acknowledge an invite.
In 99% of cases, this is because the homeserver cannot reach the appservice. Synapse for example will log an error like:
```log
synapse.http.client - 422 - INFO - as-recoverer-339 - Error sending request to PUT http://yourhookshoturl/_matrix/app/v1/transactions/123: ConnectionRefusedError Connection refused
synapse.appservice.api - 405 - WARNING - as-recoverer-339 - push_bulk to http://yourhookshoturl threw exception(ConnectionRefusedError) Connection was refused by other side: 111: Connection refused. args=('Connection refused',)
synapse.appservice.scheduler - 480 - INFO - as-recoverer-339 - Scheduling retries on hookshot in Ns
```
It's hard to offer targeted advice on resolving networking issues, but a good thing to try is to check whether
you can reach hookshot at all from the homeservers environment. For instance:
```sh
$ curl http://yourhookshoturl/_matrix/app/
```
should give you a response (even if it's an error).
### Docker
It is also worth noting that if you are in a docker environment, the `url` in your registration YAML file **must** match the
path Synapse expects to reach the service on. So if your container is called `hookshot` and it's configured to listen
on port `9993`, then you should configure the `url` to be `http://hookshot:9993`.
## 2. The bot joins, but doesn't respond to my messages.
Check that you are sending the right format message. `!hookshot help` should always work.
Otherwise, check whether the room is encrypted and you haven't [enabled encryption](./advanced/encryption.html) for the bot.
The bot will ignore any messages in encrypted rooms.
You'll need to either create the room as unencrypted or enable encryption for the bot.
If this doesn't resolve your issue, check [Problem #1](#1-the-hookshot-bot-doesnt-acknowledge-an-invite) to make
sure it's not a networking issue.
## 3. The bot works, but is offline in my client.
This is expected. Hookshot doesn't support "presence" which is how Matrix determines online/offline status.