Launching: Troubleshooting (Redshift)

Launching: Troubleshooting (Redshift)


The below Q&A troubleshooting guide will hopefully resolve any issues you may have when setting up the product for the first time. If you’re still having problems, please Contact Matillion Support.


Q. The product cannot get through loading my Project

A: Matillion ETL relies on websockets for its communications and is therefore reliant on the user having access to a compatible internet browser and modern, stable internet connection. Weaker connections with either low bandwidth or high latency may experience problems loading Matillion ETL, especially when loading very large Projects.


Q. The product loads, but then immediately says “Connection lost”. What gives?

A. The “Connection” that is being lost refers to a websocket connection. Once the site loads, all further communication is done over a websocket in order to broadcast changes to other users.

If your browser is not directly connected to the Matillion instance then this error may occur. There could be an EC2 Load balancer and/or a proxy server between your browser and the Matillion instance.

Note: We recommend using an ALB rather than ELB for most situations.

For EC2 Load Balancers, log into your AWS account and browse to the EC2 services through Services → EC2 at the upper left corner of the page.

Clicking on the EC2 option brings users to the EC2 services page where 'Load Balancers' can be selected from the lists of options. If there are no load balancers associated with this account then it is likely a proxy is the cause of this issue. Select edit the applicable load balancer and re-configure the “Listeners” to use TCP instead of HTTP (and SSL instead of HTTPS, if you want to use SSL connections).

Since Websocket connections start as HTTP requests (with some special headers), proxy servers may choose to buffer, compress or otherwise change the data. If your proxy cannot be configured to support websockets, then enabling SSL and accessing Matillion over SSL (HTTPS) will usually work since the proxy will pass the encrypted data along unchanged.

Q. “Create Project” can’t find any Redshift clusters. How do I get connected?

A. Matillion uses the AWS API’s to discover Redshift instances running inside the same region as the Matillion instance.<

  • If the IAM Role attached to the instance does not have the permission to list the Redshift clusters, then the Cluster section will be empty. You can add such a policy.
  • If you did not attach an IAM role, this can be worked around - refer to the documentation on Managing Credentials to see how to add manual API keys and set them as the active credentials.
  • If your Redshift cluster is in a different region, you should consider moving Matillion to the same region as it will reduce latency between the instance and Redshift.
  • Regardless of API availability or being in a different region, you can always connect to any Redshift cluster by manually completing the connection settings during project creation. Most of the settings can be retrieved from the AWS Console for your account. Security groups must still allow connections to redshift that originate from the Matillion instance.

Q. Matillion cannot connect to Redshift, but I don’t know why. Any ideas?

A. If you see the error Connection attempt timed out while editing or creating a project.

Most commonly this is related to security groups. Often the security group assigned to the Redshift cluster and the security group assigned to the Matillion instance are different groups.

To resolve this issue add the Matillion security group as an inbound rule to the VPC Security Group section in the Redshift Cluster configuration:

  • In Services → Redshift → <cluster name> → VPC Security Groups
  • Under the Inbound tab click Edit then Add Rule.
  • Add a new rule with Type:Redshift and Source set to name of the security group assigned to the Matillion ETL instance

Q. I forgot to launch the product with an IAM role attached, but need to use features that require access to the AWS API’s. How do I provide credentials?

A. See this article which explains how to use an IAM User instead of an IAM Role.


Q. The Matillion instance has a login page. What is the username and password?

A. From version 1.21.5, new instances are launched with security enabled by default. On first launch, the username is set to “ec2-user” and the password is set to the newly created instance ID.

See this article for more information on how to add additional users and how to change the default password, or even to turn security off altogether.

Since matillion have no access or control over your own AWS resources, we cannot reset or manage passwords for you.


Q. How can I add additional users?

A. See this article for more information on how to add additional users and how to change the default password.


Q. I have set-up integration with my corporate directory server, but no-one can log in. What could be wrong?

A. Many directory servers will only talk over a secure connection. So if you have configured a connection URL such as:


Then try...


You must also provide a username and password for the initial bind, as many servers reject anonymous binds.


Q. I needed to resize the cluster but after using Matillion, the resize fails. How can I resize my cluster?

A. Matillion creates database views, unfortunately views containing Window Functions that rely on an 'Order By' clause cause a cluster resize to fail. Matillion reported this to amazon with a reproducible test case many month ago, so a fix is probably not going to be provided anytime soon.

To fix, remove all views from the cluster prior to resizing. You can remove all views for a given environment by right clicking on it and selecting 'Delete Views'.

Matillion will automatically recreate the views on the next job validation or run, so be sure to resize the cluster before any jobs are run.


Q. When using Matillion over SSL, my browser warns me the site isn’t secure. Why is this?

A. We generate self-signed SSL certificates for each version, and so the browser cannot validate them. You may use your own certificates provided by AWS or another provider by uploading them.

See this article for information about managing the server, including a way to upload new certificates.


Q. I don't have direct access to Matillion, How can I tunnel Matillion ETL?

A. Matillion treats localhost as a special case so to tunnel Matillion you will need to bind to a local adapter. e.g. If you use ssh to create the tunnel use the following syntax.

ssh -i <keyfile>.pem ec2-user@<Matillion IP> -L <local IP>:8080:<Matillion IP>:8080

Note: The <local IP> parameter is optional but Matillion would recommend explicitly specifying a Local IP Address. Do not bind to localhost or as this may hinder the websocket connection required by Matillion ETL. Users need to create an entry in the host file to map to an IP to access the Matillion ETL instance. Accessing via localhost will not work.

Then use the local IP to connect e.g.

http://<local IP>:8080/

Alternatively if you are creating the tunnel in putty you will need to tick "Local ports accept connections from other hosts". e.g.


Q. Should I use ELB or ALB?

A. For the end user, the difference can often be that ELB requires additional configuration while ALB generally works 'out of the box'. A description on ELB ('classic') and ALB can be found in the Amazon documentation and a direct comparison between the load balancers can be found here.

We generally recommend using an ALB with Matillion ETL.