---
layout: docs
page_title: Tips and Troubleshooting
description: |-
  Waypoint is a work in progress, and this page provides tips for how to troubleshoot any issues that you might encounter while deploying applications.
---

# Tips and Troubleshooting

## Remove the Waypoint Server

The Waypoint Server creates several resources in Docker and Kubernetes that should be removed to either reinstall Waypoint or to completely remove it from a system.

Run `waypoint destroy` on your workspaces prior to removing the server to prevent hanging resources.

### Uninstall

Starting in 0.2.1, the `server uninstall` command will remove the server and supporting
containers and services that are created via `install`. By default, it also creates
a snapshot and deletes the server context.

For Docker, `uninstall` removes the Waypoint server-specific volumes, but refrains from
doing a global volume prune. If you created deployments with Waypoint, there will likely
be volumes left over from those deployments. You can remove these volumes individually,
or globally via:

```shell-session
$ docker volume prune -f
```

If the uninstall fails, see below for manual removal.

### Manual removal

#### Waypoint Server in Docker

Ensure that you have the latest `hashicorp/waypoint` Docker image.

```shell-session
$ docker pull hashicorp/waypoint:latest
```

[`waypoint install`] for Docker creates a container and a volume. These resources should be removed when Waypoint Server is no longer needed. These are some example `docker` commands that should clean up after a Waypoint Server installation.

```shell-session
$ docker stop waypoint-server
$ docker rm waypoint-server
$ docker volume prune -f
```

#### Waypoint Server in Kubernetes

[`waypoint install`] for Kubernetes creates a [StatefulSet][k8s.sts], [Service][k8s.svc], [PersistentVolumeClaim][k8s.pvc], and a [Deployment][k8s.deploy].
These resources should be removed when Waypoint Server is no longer needed. These are some example `kubectl` commands that should
clean up after a Waypoint Server installation.

[`waypoint install`]: /commands/install
[k8s.sts]: https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/
[k8s.svc]: https://kubernetes.io/docs/concepts/services-networking/service/
[k8s.pvc]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims
[k8s.deploy]: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/

```shell-session
$ kubectl delete sts waypoint-server
$ kubectl delete pvc data-waypoint-server-0
$ kubectl delete svc waypoint
$ kubectl delete deploy waypoint-runner
```

## Pack Builder No Such Image

If the `pack` builder exits during build with an error similar to:

```
» Building...
Creating new buildpack-based image using builder: heroku/buildpacks:18
...
! failed to create 'detector' container: Error response from daemon: No such
  image: pack.local/builder/6c647962686577687270:latest
```

You may need to remove the Docker volumes that are responsible for storing cached images for pack.

```shell-session
$ docker volume list
...
```

Locate the volumes named starting with `pack-cache-` and remove them with `docker volume rm`.

## Remote Operations Failure

If your Waypoint operation with remote runners fails, task introspection can help
troubleshoot the issue. Logs from the on-demand runner may not be readily available
from the platform in which the runners are launched, and task introspection can
get the information needed to troubleshoot.

In the example below, after a build failure, `waypoint task inspect` was used
with the task ID. The Run Job results show that there was an error with the Docker
plugin which required arguments which were missing:

```terminal-output
waypoint task inspect 01G669RE32WM0JBBGZW3JETYSJ

» On-Demand Runner Task Configuration
      Task ID: 01G669RE32WM0JBBGZW3JETYSJ
   Task State: STOPPED
    Workspace: default
      Project: example-go
  Application: example-go

» Run Job Configuration
  Job Configuration:
         Job ID: 01G669RE30ND9SKP50RYWP1B5H
      Operation: Build
  Target Runner: 01G669RE300HV2D1QPSYMSKHP2
      Workspace: default
        Project: example-go
    Application: example-go

  Job Results:
           State: Error
   Complete Time: 33 minutes ago
  Error Messsage: There was an error while executing a Waypoint plugin for this operation!

One or more required arguments for the plugin was not satisfied. This is usually due to a missing or incompatible set of plugins. For example, only certain build plugins are only compatible with certain registries, and so on. Please inspect the missing argument, the set
of plugins you are using, and the documentation to determine if your plugin combination is valid.

Plugin function: github.com/hashicorp/waypoint/builtin/pack.(*Builder).BuildODR-fm

==> Missing arguments:

    - docker.AccessInfo


» Watch Job Configuration
  Job Configuration:
         Job ID: 01G669RE32M1MGQBYAVND110SS
      Operation: WatchTask
  Target Runner: *
      Workspace: default
        Project: example-go
    Application: example-go

  Job Results:
          State: Success
  Complete Time: 33 minutes ago

» Start Job Configuration
  Job Configuration:
         Job ID: 01G669RE32M558VJZKRGYQ9W3S
      Operation: StartTask
  Target Runner: *
      Workspace: default
        Project: example-go
    Application: example-go

  Job Results:
          State: Success
  Complete Time: 33 minutes ago

» Stop Job Configuration
  Job Configuration:
         Job ID: 01G669RE32HSPGP4AXDSA0NZ7S
      Operation: StopTask
  Target Runner: *
      Workspace: default
        Project: example-go
    Application: example-go

  Job Results:
          State: Success
  Complete Time: 33 minutes ago
```

# Investigating Deployed Applications

Waypoint includes several commands to support debugging and monitoring while
developing your application.

## Exec Into the Application Container

After deploying your application, you can use `waypoint exec` to run
commands in the context of the most recent deployment. Typically, `waypoint exec` will be used for running database migrations and debugging. However, you
can use it for any purpose.

Use the `exec` command to open a shell prompt.

```shell-session
$ waypoint exec /bin/bash
```

Since you are in the deployment directory, you will observe that Waypoint
automatically executes against the currently deployed application.

From within the Docker container, validate that this is the actual application
by listing out the directory hosting the application's compiled files. For example, if you used the `pack` builder this directory will be `/workspace`.

```shell-session
$ cd / && ls
```

You should observe an output that contains the file structure for the current
deployment.

List the processes that are running in the container.

```shell-session
$ ps aux
```

Type `exit` to leave the interactive Docker session.

```shell-session
$ exit
```

## View Waypoint Application and Entrypoint Logs

In the application's directory, run the `logs` command to observe the running
logs for your deployment. This will include logs from the
[entrypoint](/docs/entrypoint) if it is in use.

```shell-session
$ waypoint logs
```

You will observe output similar to the following. These logs are from the
existing deployment.

```plaintext
2020-09-24T06:20:18.162Z 2MGFF4:
2020-09-24T06:20:18.163Z 2MGFF4: > node-js-getting-started@0.3.0 start /workspace
2020-09-24T06:20:18.163Z 2MGFF4: > node index.js
2020-09-24T06:20:18.163Z 2MGFF4:
2020-09-24T06:20:18.383Z 2MGFF4: Listening on 3000
```

Press `Ctrl-C` to exit the `logs` command.

You may increase the verbosity of entrypoint logs by setting the
`WAYPOINT_LOG_LEVEL` environment variable. See the documentation on
[entrypoint logs](/docs/entrypoint#logging) for more information.

## Access the Waypoint web UI

The Waypoint server includes a web-based user interface that you can use to view
builds, deployments, and releases for projects and applications.

<Tabs>
<Tab heading="Local">

The web UI requires authentication. Run a single command to automatically open
the browser and authenticate your session. This command will work if a graphical
web browser is available on the machine where the command is being run.

```shell-session
$ waypoint ui -authenticate
```

</Tab>
<Tab heading="Remote">

If you are running commands on a remote server or within a virtual environment
like WSL2 for Windows, you must generate a token that can be used to
authenticate to the Waypoint web UI.

```shell-session
$ waypoint user token
```

~> **NOTE**: The token is approximately 100 characters long and will not wrap if
your terminal window is smaller than the length of the token. If authentication
fails, expand your terminal window until you can view the entire token.

Visit the Waypoint UI at port `9702` on the URL of the machine where you are
running the Waypoint server. Paste the token into the authentication field.

</Tab>
</Tabs>

~> **NOTE**: Waypoint currently uses self-signed certificates for TLS. Your web
browser will require you to bypass a certificate warning to use the UI.

Review the application metadata and associated operations and logs in the browser.
